12.SpringDoc OpenAPI 功能介绍(用于生成API接口文档)

SpringDoc OpenAPI 是一个基于 OpenAPI 3.0/3.1 规范的工具，用于为 Spring Boot 应用生成 API 文档。它是 springfox（Swagger 2.x）的现代替代方案，完全支持 Spring Boot 3.x 和 JDK 17+，具有更强的兼容性和功能。

1. SpringDoc OpenAPI 核心概念

(1) OpenAPI 规范

OpenAPI（原 Swagger 规范）是描述 RESTful API 的行业标准，支持 API 文档、测试和客户端代码生成。
SpringDoc OpenAPI 自动将 Spring Boot 的控制器、模型等转换为 OpenAPI 格式，并生成交互式 UI（Swagger UI）。

(2) 与 Spring Boot 的集成

自动扫描：无需手动配置，SpringDoc 会自动扫描 @RestController、@RequestMapping 等注解的 API。
注解支持：通过 @Operation、@Tag 等注解丰富文档内容。
支持现代技术栈：兼容 WebFlux、Kotlin、Jakarta EE 9+ 等。

(3) 关键组件

OpenAPI 对象：定义 API 的元信息（标题、描述、版本等）。
@Tag 注解：对 API 进行分类（如用户管理、订单管理）。
@Operation 注解：描述单个 API 操作（如 GET、POST）。
@Schema 注解：描述模型类的字段（如用户 ID、用户名）。

2. SpringDoc OpenAPI 核心知识点

(1) 依赖与版本

Maven 依赖：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.3.0</version> <!-- 最新稳定版 -->
</dependency>

版本选择：
- 2.x 系列支持 Spring Boot 3.x 和 OpenAPI 3.0。
- 如果需要 OpenAPI 3.1，可以使用 springdoc-openapi-starter-webmvc-api。

(2) 配置方式

自动配置：
- 默认配置下，SpringDoc 会自动生成 API 文档，无需额外代码。
自定义配置：
- 通过 OpenAPI 对象自定义元信息（如标题、描述）。
- 通过 @Tag 和 @Operation 注解补充 API 细节。

(3) 常用注解

注解	作用
`@Tag`	对 API 进行分类（如 `@Tag(name = "用户管理")`）。
`@Operation`	描述单个 API 操作（如 `@Operation(summary = "获取用户")`）。
`@Schema`	描述模型类的字段（如 `@Schema(description = "用户ID")`）。
`@Parameter`	描述请求参数（如 `@Parameter(description = "用户ID")`）。
`@ApiResponse`	描述响应状态码和内容（如 `@ApiResponse(responseCode = "200")`）。

(4) 执行路径

Swagger UI 路径：

默认访问：http://localhost:8080/swagger-ui.html。

可通过配置修改路径：

@Bean
public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public").pathsToMatch("/public/**").build();
}

OpenAPI JSON 路径：
- 默认访问：http://localhost:8080/v3/api-docs。
- 支持分组 API 的 JSON 路径（如 /v3/api-docs/public）。

3. SpringDoc OpenAPI 的工作流程

启动应用：
- SpringDoc 自动扫描所有 @RestController 和 @RequestMapping 注解的 API。
生成文档：
- 根据控制器、模型和注解生成 OpenAPI 3.0/3.1 格式的 JSON。
渲染 UI：
- 通过 Swagger UI 渲染交互式文档，支持测试 API。

4. 高级功能

(1) 分组 API

将 API 按功能分组（如公共 API、管理员 API）：

@Bean
public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public").pathsToMatch("/public/**").build();
}

访问分组后的 Swagger UI：
- http://localhost:8080/swagger-ui/index.html#/public

(2) 安全性集成

如果项目启用了 Spring Security，需要允许访问 Swagger UI：

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/swagger-ui.html", "/v3/api-docs/**").permitAll().anyRequest().authenticated();}
}

(3) 自定义 UI 配置

修改 Swagger UI 的标题、布局等：

@Bean
public UIConfiguration uiConfig() {return UIConfiguration.builder().deepLinking(true).displayOperationId(false).docExpansion(DocExpansion.NONE).build();
}

(4) 支持 OpenAPI 3.1

使用 springdoc-openapi-starter-webmvc-api 依赖：

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

5. 与 Spring Boot 3.x 的兼容性

为什么不用 springfox？
- springfox（Swagger 2.x）依赖了已移除的 Spring MVC 组件（如 PathPatternParser），无法与 Spring Boot 3.x 兼容。
- SpringDoc OpenAPI 是专门为 Spring Boot 3.x 和 Jakarta EE 9+ 设计的。

6. 总结

优势：
- 完全兼容 Spring Boot 3.x 和 JDK 17+。
- 支持 OpenAPI 3.0/3.1，功能更强大。
- 无需手动配置，自动扫描 API。
适用场景：
- 需要快速生成 API 文档的 Spring Boot 项目。
- 需要支持 OpenAPI 3.0/3.1 的现代应用。
对比 springfox：
- SpringDoc 是 springfox 的替代方案，推荐在新项目中使用。