【狂神说】Swagger入门

Swagger

1、Swagger简介

前后端分离时代（流行的：Vue+SpringBoot）

• 后端：控制层、业务层、数据访问层
• 前端：前端控制层、视图层
  • 前端可以伪造数据，不需要后端

前后端优点

• 前后端数据交互通过API
• 前后端相对独立，松耦合
• 前后端甚至可以部署在不同的服务器上

产生问题

• 前后端协调，可能会存在冲突问题

解决方法

• 制定schema计划纲要
• 制定word文档计划
• 前后端分离
  • 前端测试后端接口
  • 后端提供接口，并进行及时更新最新消息和改动

1.1、Swagger

• 号称世界上最流行的API框架
• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
• 直接运行，在线测试API
• 支持多种语言 （如：Java，PHP等）

2、SpringBoot集成Swagger

2.1、集成

• 新建SpringBoot项目（并添加web依赖支持）

• 导入相关依赖

  <!--刚开始使用3.0.0版本不能访问jar包，然后就降了jar包版本-->
  <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>
  

• 编写HelloController，测试项目搭建没有问题

• 要使用Swagger还需要编写它对应的配置类

  import org.springframework.context.annotation.Configuration;
  import springfox.documentation.swagger2.annotations.EnableSwagger2;
  
  @Configuration//java配置类
  @EnableSwagger2//开启Swagger2的自动配置
  public class SwaggerConfig {
  }
  

• 访问测试：http://localhost:8080/swagger-ui.html 进入Swagger界面

  

2.2、拓展

# 搞清楚这行代码是干什么的
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3、配置Swagger

3.1、修改Swagger的默认信息

• 注入Docket的bean实例（Swagger的实例是Docket）

  @Bean//注入Docket类型的bean来配置（自定义）Swagger的具体参数
  public Docket getDocket(){
    //通过该类的apiInfo方法来修改默认的配置信息
    return new Docket(DocumentationType.SWAGGER_2);
  }
  

• 修改默认的的Swagger信息

  通过调用Docket对象的apiInfo方法）

  注意：apiInfo方法的参数类型是ApiInfo类型

  @Bean//注入Docket类型的bean来配置（自定义）Swagger的具体参数
  public Docket getDocket(){
    //通过该类的apiInfo方法来修改默认的配置信息
    return new Docket(DocumentationType.SWAGGER_2).apiInfo();
  }
  

  

• 修改ApiInfo类中的默认配置信息

  public ApiInfo apiInfo(){
    Contact contact = new Contact("mtf", "https://baidu.com", "2224909659@qq.com");
  
    return new ApiInfo("mtf学习Swagger",
                       "边学边总结",
                       "a1.0",
                       "urn:tos",
                       contact,
                       "Apache 2.0",
                       "http://www.apache.org/licenses/LICENSE-2.0",
                       new ArrayList());
  }
  

• 最后调用该方法，返回的ApiInfo类实例赋值给apiInfo方法

  @Bean//注入Docket类型的bean来配置（自定义）Swagger的具体参数
  public Docket getDocket(){
    //通过该类的apiInfo方法来修改默认的配置信息
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
  }
  

  

3.2、配置扫描接口

指定要扫描的接口

• 构造Docket类实例时通过调用select方法配置

• 之后通过调用apis() 方法

  

  @Bean//注入Docket类型的bean来配置（自定义）Swagger的具体参数
  public Docket getDocket(){
    //通过该类的apiInfo方法来修改默认的配置信息
    return new Docket(DocumentationType.SWAGGER_2).
      apiInfo(apiInfo())
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.mtf.controller"))
      .build();
  }
  

过滤（不扫描）

• 构造Docket类实例时通过调用select方法配置

• 之后通过调用 paths() 方法

  

  @Bean//注入Docket类型的bean来配置（自定义）Swagger的具体参数
  public Docket getDocket(){
    //通过该类的apiInfo方法来修改默认的配置信息
    return new Docket(DocumentationType.SWAGGER_2).
      apiInfo(apiInfo())
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.mtf.controller"))
      //过滤掉该路径下的所有接口，意识就是不扫描下面路径的所有接口
      .paths(PathSelectors.ant("../controller/**"))
      //上面设置相当于什么也没有扫描
      .build();
  }
  

3.3、配置Swagger开关

• 构造Docket类实例时通过调用enable方法配置

  

  @Bean//注入Docket类型的bean来配置（自定义）Swagger的具体参数
  public Docket getDocket(){
    //通过该类的apiInfo方法来修改默认的配置信息
    return new Docket(DocumentationType.SWAGGER_2).
      apiInfo(apiInfo())
      .enable(false)
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.mtf.controller"))
      //过滤掉该路径下的所有接口，意识就是不扫描下面路径的所有接口
      //.paths(PathSelectors.ant("../controller/**"))
      .build();
  }
  

思考：在开发环境中开启Swagger，在发布环境中关闭Swagger

• 首先：需要判断环境
• 其次：开启和关闭Swagger

@Bean//注入Docket类型的bean来配置（自定义）Swagger的具体参数
public Docket getDocket(Environment environment){
  //设置要使用Swagger的环境
  Profiles profiles = Profiles.of("pro");
  //判断当前是否处于该环镜
  boolean b = environment.acceptsProfiles(profiles);

  //通过该类的apiInfo方法来修改默认的配置信息
  return new Docket(DocumentationType.SWAGGER_2).
    apiInfo(apiInfo())
    .enable(b)
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.mtf.controller"))
    //过滤掉该路径下的所有接口，意识就是不扫描下面路径的所有接口
    //.paths(PathSelectors.ant("../controller/**"))
    .build();
}

3.4、配置API分组

配置多个分组

• 构造Docket类实例时通过调用groupName方法配置

@Bean
public Docket docket1(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}

@Bean
public Docket docket2(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}

@Bean
public Docket docket3(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

实体类配置

• 创建User实体类

  package com.mtf.pojo;
  
  import io.swagger.annotations.ApiModel;
  import io.swagger.annotations.ApiModelProperty;
  //@Api等价
  @ApiModel("用户实体类")
  public class User {
    @ApiModelProperty("用户id")
    //注意这里的属性修饰符，如果用的修饰符是“private”，那么页面中的属性和属性注释不会显示
    public Integer id;
    @ApiModelProperty("用户昵称")
    public String name;
  }
  
  

• 编写控制类

  package com.mtf.controller;
  
  import com.mtf.pojo.User;
  import io.swagger.annotations.Api;
  import io.swagger.annotations.ApiOperation;
  import org.springframework.web.bind.annotation.*;
  @Api(tags = "Hello控制类")
  @RestController
  public class HelloController {
      @ApiOperation("你好Swagger")
      @GetMapping("/swagger")
      public String hello(){
          return "hello,swagger!";
      }
      @ApiOperation("获得用户")
      @PostMapping("/user")
      public User user(){
          return new User();
      }
      @ApiOperation("测试")
      @PostMapping("/test")
      public String test(){
          return "test";
      }
  }
  

  

3.5、Swagger常用注解

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

4、总结

• 通过Swagger可以添加一些难理解的类、属性的注释信息
• 接口文档实时更新
• 在线测试
• 注意：在正式发布是关闭Swagger（出于安全考虑）