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

本文主要是介绍Swagger API 文档 | SpringBoot 3.x 集成 SpringDoc，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

😎 本节目标： 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)

这篇关于Swagger API 文档 | SpringBoot 3.x 集成 SpringDoc的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！

---