因为业务的需要接口文档可能会发生改变，前后端交互上经常会出现参数不符的情况，通过Excel或者Word维护接口文档，会存在时效性较差的问题，而Swagger正是解决这一痛点的利器。在代码中加入注解，可以实时更新接口。

Swagger是一个规范且完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web服务

号称世界上最流行的API框架
RestFul API文档在线生成工具 —>>> API文档与API同步更新
可以直接运行,可以在线测试API接口
支持多种语言:(Java,PHP…..)

1.导入依赖

1.1 Swagger 3

<dependencies>
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-web</artifactId>
   </dependency>

   <!-- springfox-swagger3 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-boot-starter</artifactId>
       <version>3.0.0</version>
   </dependency>
</dependencies>

1.2 Swagger 2

<dependencies>
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-web</artifactId>
   </dependency>

   <!-- springfox-swagger2 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>

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

注：3相比2简化了依赖添加，同时注解以及配置也发生了略微变化，接下来以3为准

2.Swagger配置

@Configuration
@EnableOpenApi
public class SwaggerConfig {
   /**
    * 创建API应用
    * apiInfo() 增加API相关信息
    * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
    * 本例采用指定扫描的包路径来定义指定要建立API的目录。
    *
    * @return
    */
   @Bean
   public Docket desertsApi1() {
       return new Docket(DocumentationType.OAS_30)
          .apiInfo(apiInfo("XX项目——Swagger3.0", "1.0"))
          .select()
          .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
          .paths(PathSelectors.any())
          .build()
          .groupName("员工信息")
          .enable(true);
  }

   //再定义一个Docket
   @Bean
   public Docket desertsApi2() {
       return new Docket(DocumentationType.OAS_30)
          .apiInfo(apiInfo("XX项目——Swagger3.0", "1.0"))
          .select()
          .apis(RequestHandlerSelectors.basePackage("com.swagger.login.controller"))
          .paths(PathSelectors.any())
          .build()
          .groupName("登录")
          .enable(true);
  }

   /**
    * 创建该API的基本信息（这些基本信息会展现在文档页面中）
    * 访问地址：/swagger-ui/index.html
    *
    * @return
    */
   private ApiInfo apiInfo(String title, String version) {
       return new ApiInfoBuilder()
          .title(title)
          .description("XX项目接口测试页面")
          .contact(new Contact("墨初", "https://mochu.co", "junn127@qq.com"))
          .termsOfServiceUrl("")
          .version(version)
          .build();
  }
}

注：需要加上SpringMVC的这个配置，不然启动程序会报错

spring:
  mvc:
    path match:
      matching-strategy: ant_path_matcher

3.注解使用

3.1 注解对比

3.2 控制层

@RestController
@RequestMapping("/emp")
@Api(tags = "员工接口")
public class EmpController {

   @GetMapping("/list")
   @ApiOperation(value = "查询所有员工", notes = "将所有员工信息返回")
   public String queryAll() {
       return "你正在查询所有员工...";
  }

   @GetMapping("/{id}")
   @ApiOperation(value = "根据员工id查询员工信息", notes = "返回指定id的员工信息")
   public String queryEmpById(@PathVariable("id") Integer id) {
       return "你正在查询id为 " + id + " 的员工信息...";
  }

   @PostMapping("/add")
   @ApiOperation(value = "添加员工", notes = "根据传入信息添加员工")
   public String addEmp(@RequestBody Emp emp) {
       return "添加成功，添加的员工信息为：" + emp.toString();
  }
}

3.3 实体类

@ApiModel("员工实体类")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Emp {

   @ApiModelProperty("员工编号")
   private Integer id;

   @ApiModelProperty("员工姓名")
   private String empName;

   @ApiModelProperty("员工性别")
   private String gender;

   @ApiModelProperty("员工年龄")
   private Integer age;

}

4.启动测试

3测试地址：/swagger-ui/index.html

2测试地址：/swagger-ui.html

5.整合knife4j

knife4j可以看成Swagger的加强版

swagger-bootstrap-ui是基于springfox-swagger的增强UI实现，以文档说明和在线调试为核心，为Java开发者在使用Swagger的时候，能拥有一份简洁、强大的接口文档体验。Swagger-Bootstrap-UI 替换Swagger 默认的UI实现左右菜单风格的Swagger-UI ，让其看起来更清晰明了

swagger-bootstrap-ui 后更名为 knife4j

5.1 起步依赖

<!-- knife4j -->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-spring-boot-starter</artifactId>
   <version>3.0.3</version>
</dependency>