Swagger API 文档 | SpringBoot 3.x 集成 SpringDoc

文章目录

常规方式
- 第 1 步：添加依赖
- 第 2 步：配置 API 信息及全局参数
- - 配置 OpenAPI 文档
  - - 配置单个 OpenAPI 文档 - 方式 1
    - 配置单个 OpenAPI 文档 - 方式 2
    - 配置多个 OpenAPI 文档
  - 其它 SpringDoc 及 Swagger-UI 配置
- 第 3 步：添加 Swagger3 注解
- - Swagger2 和 Swagger3 注解对应关系
  - Swagger3 注解案例
  - - Feign 客户端及其实现 Controller
    - 通用 Response 与 Account 实体类
    - 界面效果
特殊方式 1：从 JavaDoc 生成 API 定义
- 第 1 步：添加依赖
- 第 2 步：编译项目
- 第 3 步：添加 JavaDoc 注释
- 第 4 步：最终效果
特殊方式 2：构建时生成 JSON/YAML
相关博文

😎 本节目标： SpringBoot 3.x 集成 SpringDoc（含 SpringFox 升级 SpringDoc）

常规方式：添加注解方式，然后生成 API 文档及 Swagger UI 界面
特殊方式 1：从 JavaDoc 读取 API 定义
特殊方式 2：maven 集成测试阶段生成 API 定义

👉 版本说明

JDK 17
SpringBoot 3.2.1
SpringDoc 2.3.0

🚀 官方 demo：springdoc-openapi-demos-2.x.zip

常规方式

第 1 步：添加依赖

移除 SpringFox 和 Swagger2 的相关依赖，并添加 springdoc-openapi-starter-webmvc-ui 依赖：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.3.0</version>
</dependency>

添加上述依赖后，即可访问 SwaggerUI 界面及 OpenAPI 文档。
Swagger-UI 访问效果：http://server:port/context-path/swagger-ui.html

OpenAPI 访问效果：

JSON 格式： http://server:port/context-path/v3/api-docs
YAML 格式：http://server:port/context-path/v3/api-docs.yaml

第 2 步：配置 API 信息及全局参数

上述 Swagger UI 界面中，使用的是默认的 API 信息。下面我们来自定义：

添加 API 信息，比如标题、描述等
添加全局请求 Token

下面有几种方式，可按需选择。

配置 OpenAPI 文档

配置单个 OpenAPI 文档 - 方式 1

在配置前，我们先了解一个特性：Swagger 中的有些注解，支持 Spring 配置解析。

@Info: title * description * version * termsOfService
@Info.license: name * url
@Info.contact: name * email * url
@Operation: description * summary
@Parameter: description * name
@ApiResponse: description
@OAuthFlow: openIdConnectUrl * authorizationUrl * refreshUrl * tokenUrl
@Schema: name * title * description，但需要设置 springdoc.api-docs.resolve-schema-properties=true

利用这个特性，我们使用如下配置文件进行自定义 API 信息及全局配置：

@OpenAPIDefinition(info = @Info(title = "${openapi.title: ${spring.application.name}} API文档",version = "${openapi.version: 0.0.1}",description = "${openapi.description:}",termsOfService = "${openapi.termsOfService:}",license = @License(name = "${openapi.license.name:}",url = "${openapi.license.url:}"),contact = @Contact(name = "${openapi.contact.name:}",email = "${openapi.contact.email:}",url = "${openapi.contact.url:}")),security = @SecurityRequirement(name = "JWT")
)
@SecurityScheme(type = SecuritySchemeType.HTTP, name = "JWT", scheme = "Bearer", in = SecuritySchemeIn.HEADER)
@Configuration
public class SpringDocConfig {}

这样，我们可以使用 openapi.title 定义 API 标题，使用 openapi.version 定义 API 版本。比如：

openapi:title: 业务服务version: v1.0.0

页面效果：
此外，前面定义了安全配置，即每个请求需要在请求头中加 Bearer token。在上述页面中，显示了 Authorize 按钮，可以输入 Token 值。

后续请求，就会自动带着这个 Bearer Token：

配置单个 OpenAPI 文档 - 方式 2

换个方式，一样可以实现。可以直接构造 OpenAPI 这个对象，而不是使用注解来定义。
思路和之前一样：

先定义安全 Schema：@SecurityScheme -> addSecuritySchemes
然后使用组件：security = xxx -> .addSecurityItem

@Configuration
public class SpringDocConfig {@Beanpublic OpenAPI customOpenAPI(@Value("${springdoc.version:1.0.0}") String appVersion) {return new OpenAPI()// 定义组件.components(new Components().addSecuritySchemes("JWT", new SecurityScheme().in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.HTTP)