在 Spring Boot 3.x 中用…

为 Spring Boot 3.x REST API 自动生成 OpenAPI 3.0 规范并提供可浏览、可测试的 Swagger UI 界面。

适用场景

解决思路

1. 按应用类型添加 SpringDoc starter 依赖：WebMvc 用 springdoc-openapi-starter-webmvc-ui，WebFlux 用 springdoc-openapi-starter-webflux-ui（Maven/Gradle 配置见 dependency-setup.md）。
2. 在 application.yml 中做基础配置，例如设置 springdoc.api-docs.path=/api-docs、springdoc.swagger-ui.path=/swagger-ui.html、springdoc.swagger-ui.operationsSorter=method，高级选项见 configuration.md。
3. 在 Controller 上用 OpenAPI 注解补充描述信息：类上加 @Tag(name, description)，方法上加 @Operation(summary)、@ApiResponse(responseCode, description)，模式见 controller-documentation.md。
4. 在 DTO/实体上用 @Schema 注解描述字段，例如 @Schema(example = "1", accessMode = Schema.AccessMode.READ_ONLY) 和 @Schema(example = "Clean Code", required = true)，校验模式见 model-documentation.md。
5. 在 OpenAPI Bean 中配置安全方案，例如通过 Components.addSecuritySchemes 添加 bearer-jwt（type=HTTP、scheme=bearer、bearerFormat=JWT），并在 Controller 上用 @SecurityRequirement(name = "bearer-jwt") 应用，详见 security-configuration.md。
6. 对 Spring Data Pageable 参数使用 @ParameterObject 进行分页文档化，例如 public Page<Book> findAll(@ParameterObject Pageable pageable)，详见 pagination-support.md。
7. 访问 /swagger-ui/index.html 验证文档完整性。
8. 为生产环境做定制：配置 API 分组、版本化与构建插件，见 advanced-configuration.md 和 build-integration.md。
9. 最佳实践：使用简短（< 120 字符）清晰的操作摘要。
10. 最佳实践：记录所有响应码，包括成功（2xx）、客户端错误（4xx）、服务端错误（5xx）。
11. 最佳实践：为请求/响应体添加示例，使用 @ExampleObject 提供真实示例。
12. 最佳实践：利用 JSR-303 校验注解，SpringDoc 会据此自动生成约束。
13. 最佳实践：对复杂参数（尤其是 Pageable、自定义过滤对象）使用 @ParameterObject。
14. 最佳实践：用 @Tag 按领域实体或功能对相关端点分组。
15. 最佳实践：在需要认证处用 @SecurityRequirement 记录安全要求。
16. 最佳实践：适当隐藏内部端点，使用 @Hidden 或创建单独的 API 分组。
17. 最佳实践：定制 Swagger UI 以提升体验，启用过滤、排序、try-it-out 功能。
18. 最佳实践：为 API 文档做版本管理，在 OpenAPI Info 中包含版本号。

适用边界 · 注意事项

• 不要在 API 示例或 schema 描述中暴露敏感数据。
• 不要过度堆砌 OpenAPI 注解以免污染 Controller 代码，能全局配置就全局配置。
• 不要在 DTO 中引入循环引用，否则 schema 生成会无限递归；复杂泛型类型需显式加 @Schema 注解。