Swagger2

前言

由于目前大趋势，都是进行前后端的开发模式。在这样的背景下，前后端的交流是必不可少的。相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

Swagger的诞生完美的解决了上述问题，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等

所提供的开源工具

1. Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

2. Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

3. Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

4. Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

5. Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

SpringBoot集成Swagger2

SpringFox

SpringFox是Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件，提供控制层中各个请求的测试界面等。本身不是属于Swagger官网提供的。

Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger。但是使用起来确方便很多。所以在实际开发中，都是直接使用spring-fox。

导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

使用

基本使用

1. 开启Swagger2的自动配置

   @SpringBootApplication
   @EnableSwagger2 //springfox提供的一个注解，代表swagger2相关技术开启，会扫描当前类所在包，及子包中所有的类型中注解
   public class DemoApplication {
       public static void main(String[] args) {
           SpringApplication.run(DemoApplication.class, args);
       }
   }

2. 进行swagger-ui页面：http://localhost:8011/swagger-ui.html

   

3. 可以点击try it out进行请求的模拟

   

swagger配置

修改api文档顶部主体内容

• 创建配置类

  import org.springframework.context.annotation.Bean;
  import org.springframework.context.annotation.Configuration;
  import springfox.documentation.builders.ApiInfoBuilder;
  import springfox.documentation.service.ApiInfo;
  import springfox.documentation.service.Contact;
  import springfox.documentation.spi.DocumentationType;
  import springfox.documentation.spring.web.plugins.Docket;
  
  @Configuration
  public class SwagggerConfiguration {
      /**
       * 创建Docket类型的对象，交由spring容器管理
       * Docket是Swagger中的全局配置对象
       * @return
       */
      @Bean
      public Docket docket(){
          //指定swagger版本
          Docket docket = new Docket(DocumentationType.SWAGGER_2);
  
          //api帮助文档的描述信息
          ApiInfo apiInfo =
                  new ApiInfoBuilder()
                          .contact( //主体内容：发布者名称、发布者网站地址、发布者邮箱
                                  new Contact("wht",
                                          "http://www.wht.com",
                                          "1369281736@qq.com")
                          )
                          //文档题目
                          .title("SwaggerApi学习帮助文档")
                          //文档描述
                          .description("一个简单学习使用Swagger2的文档")
                          //文档版本
                          .version("1.1")
                          .build();
  
          docket.apiInfo(apiInfo);
         
          
          return docket;
      }
  }

• 效果：

  

配置扫描接口

docket
    //获取Docket中的选择器，返回ApiSeletorBuilder
    .select()
    //指定扫描的规则
    //指定扫描com.wht.controller包及其子包
    .apis(RequestHandlerSelectors.basePackage("com.wht.controller"));

除了basePackage的扫描策略还有其他的：

• any() ：扫描所有，项目中的所有接口都会被扫描到
• none()： 不扫描接口
• withMethodAnnotation(final Class<? extends Annotation> annotation)： 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
• withClassAnnotation(final Class<? extends Annotation> annotation) ： 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口

添加请求路径过滤器

.apis(RequestHandlerSelectors.basePackage("com.wht.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/user开头的接口
.paths(PathSelectors.ant("/user/**"))

除了ant()风格的扫描策略还有其他的：

• any() ：任何请求都扫描
• none()：任何请求都不扫描
• regex(final String pathRegex)：通过正则表达式控制

根据环境动态展示swagger

@Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean flag = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(flag) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.wht.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/user开头的接口
      .paths(PathSelectors.ant("/user/**"))
      .build();
}

分组

如果没有对分组进行配置，默认只有default分组，可以通过groupName(“组名”)进行分组

例子：

@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

常用注解

• @Api(tags = “xxx模块说明”) ：对模块进行描述
• @ApiOperation(“xxx接口说明”)：对api接口的描述
• @ApiModel(“xxxPOJO说明”)：对javaBean进行描述
• @ApiModelProperty(value = “xxx属性说明”,hidden = true)：对javaBean的属性进行描述
• @ApiParam(“xxx参数说明”)：对方法参数进行描述
• @ApiIgnore：加在方法或类上不生成文档
• @ApiImplicitParam(name = “参数名”,value = “参数描述”, required = “是否必要” , paramType = “参数类型”)：加在接口上用于描述接口中的参数
• @ApiImplicitParams(name = {@ApiImplicitParam(),@ApiImplicitParam()})：定义多个参数