Spring Boot 使用 SpringDoc 库的 Swagger3.0

Posted 2022-12-30 福州司马懿

Swagger 定义

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

SpringFox 的 Swagger 库

之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库，上了下官网发现已经有接近两年没出新版本了！前几天升级了SpringBoot 2.6.x 版本，发现这个库的兼容性也越来越不好了，有的常用注解属性被废弃了居然都没提供替代！

https://search.maven.org/ 网站上可以查到它的最近一次版本发布时时间：14-Jul-2020。

引入依赖的方式如下

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

Spring5使用PATH_PATTERN_PARSER来替代原本的ANT_PATH_MATCHER。SpringBoot2.6.0开始，Spring默认路径匹配策略从ANT_PATH_MATCHER改成PATH_PATTERN_PARSER。但Swagger没有对其做兼容，因此会报空指针异常。需要修改application.yml，添加如下配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

SpringDoc

后来在网上一查发现，现在大家都在用另一款Swagger库SpringDoc。官网地址为：https://springdoc.org/

SpringDoc是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI 3，目前在Github上已有1.7K+Star，更新发版还是挺勤快的，是一款更好用的Swagger库！值得一提的是SpringDoc不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目，总之非常强大

依赖

https://search.maven.org/ 网站上可以查到它的最近一次版本发布时时间：16-Dec-2022。

引入依赖的方式如下

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

包名

• 2.9.x
  • io.swagger
• 3.0.0
  • io.swagger.core.v3
  • io.swagger.v3.oas.annotations

注解

这一步是可选的，因为改动太大，故 springfox对旧版的 swagger做了兼容处理。

Swagger2 的注解命名以易用性切入，全是 Api 开头，在培养出使用者依赖注解的习惯后，Swagger 3将注解名称规范化，工程化。

swagger2	OpenAPI 3	注解位置
@Api	@Tag(name=“接口描述”, description = “详细说明”)	Controller类上
@ApiOperation	@Operation(summary = “接口方法描述”, description = “详细说明”)	Controller方法上
@ApiImplicitParams	@Parameters	Controller 方法上
@ApiImplicitParam	@Parameter(description=“参数描述”)	Controller 方法上 @Parameters 里
@ApiParam	@Parameter(description=“参数描述”)	Controller 方法的参数上
@ApiIgnore	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	-
@ApiModel	@Schema	DTO类上(Data Transfer Object)
@ApiModelProperty	@Schema	DTO属性上(Data Transfer Object)

常用配置

SpringDoc还有一些常用的配置

springdoc:
  swagger-ui:
    # 修改Swagger UI路径
    path: /swagger-ui.html
    # 开启Swagger UI界面
    enabled: true
  api-docs:
    # 修改api-docs路径
    path: /v3/api-docs
    # 开启api-docs
    enabled: true
  # 配置需要生成接口文档的扫描包
  packages-to-scan: com.macro.mall.tiny.controller
  # 配置需要生成接口文档的接口路径
  paths-to-match: /brand/**,/admin/**

访问地址

• 2.9.x
  http://localhost:8081/context-path/swagger-ui.html
• 3.0.0
  http://localhost:8081/context-path/swagger-ui/index.html

英文单词解释

• explicit关键字
  只能修饰只有一个参数的构造函数，或者有多个参数，但是除第一个参数外其他的参数都有默认值。它的作用是表明构造函数是显式方式显示的(当我们不希望自动类型转换的时候用。标准库好多构造函数都是explicit的)
• implicit关键字
  与explicit对应，他表示隐式的进行数据转换(在需要隐式转换的时候用)。注：C++中不存在这个关键字，C#等编程语言中才有
• DTO
  Data Transfer Object，即数据传输对象。用于表现层和应用层之间的数据交互 简单来说Model面向业务，我们是通过业务来定义Model的。而DTO是面向界面UI，是通过UI的需求来定义的。 通过DTO我们实现了表现层与Model之间的解耦，表现层不引用Model(个人理解，就是Java Bean)
• Controller
  Spring Controller本身也是一个Spring Bean，只是它多提供了Web能力，只需要造类上提供 @Controller 或者 @RestController 注解即可