Swagger2

Swagger简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

• 接口的文档在线自动生成。

• 功能测试。

Spring boot集成Swagger

• 新建一个springboot项目

• 添加Maven依赖

  <!--Swagger2依赖 -->
  <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.9.2</version>
  </dependency>
  <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
  </dependency>
  

• 编写一个HelloWord工程

  @RestController
  public class HelloController {
      @GetMapping("/Hello")
      public String sayHello(){
          return "Hello";
      }
  }
  

• 配置Swagger,编写配置类

  @Configuration //配置类
  @EnableSwagger2 // 开启Swagger2的自动配置
  public class SwaggerConfig {  
  }
  

  注意：这里直接使用默认值测试

• 重启项目，访问 http://localhost:8080/swagger-ui.html

Swagger详细配置

配置基本信息

private ApiInfo apiInfo() {
    //作者信息 名字，链接，邮箱
    Contact contact = new Contact("lbb", "https://blog.csdn.net/bing_bg", "lbb@163.com");
    return new ApiInfo("lbb的Api文档", //题目
            "这是最牛逼的项目",  //描述
            "v1.0",  //版本
            "https://blog.csdn.net/bing_bg",  // 组织链接
            contact, // 联系人信息
            "Apache 2.0",  // 许可
            "http://www.apache.org/licenses/LICENSE-2.0", // 许可连接
            new ArrayList());// 扩展
}

配置Swagger的Bean实例

在上面建的配置类中配置Swagger的Bean实例，部分配置如下：

//配置Swagger的Bean实例
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()// 通过.select()方法，去配置扫描接口,下面 RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.lbb.swagger_demo.controller"))
            .build();
}

• RequestHandlerSelectors的方法：

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

接口扫描过滤 paths方法

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.lbb.swagger_demo.controller"))
       
       // 配置如何通过path过滤,即这里只扫描请求以/lbb开头的接口
      .paths(PathSelectors.ant("/lbb/**"))
      .build();
}

• PathSelectors的方法：

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

配置Swagger开关 enable方法

• 通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

  //配置Swagger的Bean实例
      @Bean
      public Docket docket() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  
                  .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
  
                  .select()// 通过.select()方法，去配置扫描接口,下面 RequestHandlerSelectors配置如何扫描接口
        .apis(RequestHandlerSelectors.basePackage("com.lbb.swagger_demo.controller"))
                  // 配置如何通过path过滤,即这里只扫描请求以/lbb开头的接口
                  .paths(PathSelectors.ant("/lbb/**"))
                  .build();
      }
  

• 动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示

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

配置API分组

• 没有配置分组，默认是default。通过groupName()方法即可配置分组：

  @Bean
  public Docket docket(Environment environment) {
     return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        .groupName("hello"); // 配置分组
  }
  

• 配置多个分组

  @Bean
  public Docket docket1(){
     return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        .groupName("lbb1"); // 配置分组1
  }
  @Bean
  public Docket docket2(){
     return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        .groupName("lbb2"); // 配置分组2
  }
  @Bean
  public Docket docket3(){
     return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
        .groupName("lbb3"); // 配置分组3
  }
  

实体配置

• 新建一个实体类

  @ApiModel("用户实体")
  public class User {
     @ApiModelProperty("用户名")
     public String username;
     @ApiModelProperty("密码")
     public String password;
  }
  

  注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。其中 @ApiModel为类添加注释，@ApiModelProperty为类属性添加注释。

• 实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

  @GetMapping("/getUser")
  public User getUser(){
     return new User();
  }
  

• 重启查看测试

常用注解

Swagger的所有注解定义在io.swagger.annotations包下,常用注解如下:

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

• 可以给请求的接口配置一些注释

  @ApiOperation("lbb的接口")
  @PostMapping("/lbb")
  @ResponseBody
  public String lbb(@ApiParam("这个名字会被返回")String username){
     return username;
  }
  

  运行查看即可！

皮肤扩展

• 默认的，访问 http://localhost:8080/swagger-ui.html

  <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
  </dependency>
  

• knife4j 访问http://localhost:8080/doc.html

  <!-- 引入knife4j包 /doc.html-->
  <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>knife4j-spring-ui</artifactId>
      <version>2.0.4</version>
  </dependency>
  

• mg-ui 访问 http://localhost:8080/document.html

  <!-- 引入swagger-ui-layer包 /document.html-->
  <dependency>
     <groupId>com.zyplayer</groupId>
     <artifactId>swagger-mg-ui</artifactId>
     <version>1.0.6</version>
  </dependency>