SuperAPI AI 工具集

spring-boot-openapi-documentation

编程与开发

查看项目

更新于 10-15 21:52

技能介绍

用途:在 Spring Boot 3.x 项目中自动生成 OpenAPI 3.0 文档,并通过 Swagger UI 浏览与测试 REST API。适用于搭建文档、定制 Swagger UI、用注解补充接口说明、描述请求响应模型与校验、编写 JWT/OAuth2/Basic Auth/API Key 安全文档、记录分页排序端点、添加示例与 Schema、以编程方式定制 OpenAPI 定义、支持多分组与多版本、记录错误响应、处理异常、配合 JSR-303 校验,以及支持 Kotlin 项目。

主要能力与用法:按应用类型引入依赖,WebMvc 使用 springdoc-openapi-starter-webmvc-ui,WebFlux 使用 springdoc-openapi-starter-webflux-ui;在 application.yml 配置 springdoc.api-docs.* 与 springdoc.swagger-ui.*,如接口 JSON 路径 /v3/api-docs、UI 路径 /swagger-ui/index.html。使用 @Tag、@Operation、@ApiResponse、@Parameter、@Schema、@SecurityRequirement 等注解描述控制器与模型;分页用 @ParameterObject 配合 Pageable;安全方案在 OpenAPI Bean 中定义,再在控制器上标注;可在 Swagger UI 中验证文档完整性,并在生产环境配置分组、版本与构建集成。

限制与注意:不要在示例或 Schema 中暴露敏感数据;注解尽量精简,优先用全局配置;大型 API 定义可能影响 Swagger UI 性能,可按领域分组;复杂泛型可能导致 Schema 生成异常,需显式 @Schema;DTO 避免循环引用以免递归;使用 @SecurityRequirement 前须先正确配置安全方案;@Operation(hidden=true) 仅隐藏但代码中仍可见。