swagger使用介绍

1. 简介

号称：世界最流行的API框架

官网：http://swagger.io/

解决什么问题：在前后台分离的开发模式中，减小接口定义沟通成本，方便开发过程中测试，自动生成接口文档。

2. swagger使用方式

2.1. 第一种

定义YAML文件，然后可以生成各种语言的代码框架，对于后台程序员来说，较少人会愿意写出一堆YAML格式。

2.2. 第二种

swagger有各种语言的插件，可以通过配置及少量代码，生成接口文档及测试界面。

我们多做了：一次性的配置及少量注解代码。

我们不用再做：1、到Wiki中更新接口文档；2、Postman形式的测试；3、Curl形式的测试

3. swagger java使用介绍

对于一个SpringMVC项目，使用swagger的配置如下：

3.1. pom.xml

<!-- Swagger --> <dependency>      <groupId>io.swagger</groupId>      <artifactId>swagger-core</artifactId>      <version> 1.5 . 8 </version> </dependency> <dependency>      <groupId>io.springfox</groupId>      <artifactId>springfox-swagger2</artifactId>      <version> 2.4 . 0 </version> </dependency> <dependency>      <groupId>io.springfox</groupId>      <artifactId>springfox-swagger-ui</artifactId>      <version> 2.4 . 0 </version> </dependency>

3.2. SwaggerConfiguration.java

@Configuration @EnableSwagger2 public  class  SwaggerConfiguration {      @Bean      public  Docket api() {          return  new  Docket(DocumentationType.SWAGGER_2)                  .select()                  .apis(RequestHandlerSelectors.any())                  .paths(PathSelectors.any())                  .build();      } }

3.3. SwaggerWebMvcConfigurerAdapter.java

@Configuration @EnableWebMvc @ComponentScan (basePackages =  "com.controller" ) public  class  SwaggerWebMvcConfigurerAdapter  extends  WebMvcConfigurerAdapter {        @Bean      public  ViewResolver viewResolver() {          InternalResourceViewResolver viewResolver =  new  InternalResourceViewResolver();          viewResolver.setViewClass(JstlView. class );          viewResolver.setPrefix( "/WEB-INF/views/" );          viewResolver.setSuffix( ".jsp" );          return  viewResolver;      }        @Bean      public  MessageSource messageSource() {          ResourceBundleMessageSource messageSource =  new  ResourceBundleMessageSource();          messageSource.setBasename( "messages" );          return  messageSource;      }      @Override      public  void  addResourceHandlers(ResourceHandlerRegistry registry) {          super .addResourceHandlers(registry);          registry.addResourceHandler( "swagger-ui.html" )                  .addResourceLocations( "classpath:/META-INF/resources/" );          registry.addResourceHandler( "/webjars/**" )                  .addResourceLocations( "classpath:/META-INF/resources/webjars/" );      }      @Override      public  void  configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {          configurer.enable();      } }

3.4. AppInitializer.java

public  class  AppInitializer  extends  AbstractAnnotationConfigDispatcherServletInitializer {      @Override      protected  Class<?>[] getRootConfigClasses() {          return  new  Class[] { SwaggerWebMvcConfigurerAdapter. class  };      }      @Override      protected  Class<?>[] getServletConfigClasses() {          return  null ;      }      @Override      protected  String[] getServletMappings() {          return  new  String[] {  "/"  };      } }

3.5. Controller实例

然后，只要在我们的Controller里面增加注解 ApiOperation和ApiParam 即可。

 

@Controller @RequestMapping (value =  "/stat" ) public  class  SwaggerController {            @ResponseBody      @RequestMapping (value =  "/helloworld" , method = RequestMethod.GET)      @ApiOperation (nickname =  "swagger-helloworld" , value =  "Swagger的世界" , notes =  "测试HelloWorld" )      public  String helloWorld( @ApiParam (value =  "昵称" )  @RequestParam  String nickname) {          return  "Hello world, "  + nickname;      }            @ResponseBody      @RequestMapping (value =  "/objectio" , method = RequestMethod.POST)      @ApiOperation (nickname =  "swagger-objectio" , value =  "Swagger的ObjectIO" , notes =  "测试对象输入输出" )      public  SwaggerOutput objectIo( @ApiParam (value =  "输入" )  @RequestBody  SwaggerInput input) {          SwaggerOutput output =  new  SwaggerOutput();          output.setId(input.getId());          output.setName( "Swagger" );          return  output;      } }

3.6. Web界面

启动项目，输入Http://Path/swagger-ui.html，就可以给前端展示相关的API文档，并像使用Postman以及Curl命令一样，通过Web界面进行接口测试。