springdoc openapi 是 java 项目中生成 api 文档的主流工具，基于 openapi 3 规范，自动扫描注解、零配置运行，支持 swagger ui 和 redoc，兼容 spring boot 2.x/3.x 及 jakarta ee 9+。
Java项目中生成API文档，最常用且与Spring生态集成良好的是 Springdoc OpenAPI（基于 OpenAPI 3 规范），它取代了老一代的 Swagger2，无需侵入代码、零配置即可运行，比 Swagger UI + springfox 更轻量、更稳定。
选对工具：Springdoc OpenAPI 是当前主流选择
Springfox（Swagger2）已停止维护，Springdoc OpenAPI 是官方推荐替代方案。它自动扫描 @RestController、@RequestMapping 等注解，实时生成 OpenAPI 3 JSON/YAML，并内置 Swagger UI 和 Redoc 页面。
- 支持 Spring Boot 2.x / 3.x，兼容 Jakarta EE 9+（Spring Boot 3 要求）
- 无需额外配置就能展示接口路径、参数、返回值、状态码
- 配合
@Operation、@Parameter、@ApiResponse等注解可增强文档语义
快速集成：Maven 依赖与基础配置
以 Spring Boot 2.7+ 或 3.x 为例，在 pom.xml 中添加：
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.3.0</version> <!-- Spring Boot 3.x 用此版本 --> </dependency>
若用 Spring Boot 2.x，改用：springdoc-openapi-ui（旧版 starter，如 1.6.14）
立即学习“Java免费学习笔记（深入）”；
启动应用后，默认即可访问：
/swagger-ui.html（Swagger UI 页面）
/v3/api-docs（OpenAPI 3 JSON 格式）
/docs/index.html（Redoc 页面，需额外加 springdoc-openapi-starter-webmvc-ui）
定制化文档：常用注解与配置项
纯自动扫描够用，但要写出专业文档，需补充说明性注解：
@Operation(summary = "用户登录", description = "根据账号密码获取 JWT Token")@Parameter(name = "username", description = "用户名，长度3-20", required = true)@ApiResponse(responseCode = "200", description = "登录成功，返回 token 对象")- 对请求体使用
@Schema(description = "登录凭证")注解在 DTO 类或字段上
全局配置可写在 application.yml 中：
springdoc:
api-docs:
path: /openapi.json
swagger-ui:
path: /api-docs
doc-expansion: none
theme: fluent生产环境注意事项
开发阶段开箱即用，上线前建议调整：
- 关闭文档暴露：设
springdoc.api-docs.enabled=false或通过 profile 控制 - 避免敏感信息泄露：DTO 中用
@Schema(accessMode = Schema.AccessMode.READ_ONLY)隐藏字段 - 多模块项目：确保 API 控制器所在模块引入了 springdoc 依赖
- 网关场景：若 API 经过 Spring Cloud Gateway，需配置路由透传
/v3/api-docs和静态资源路径
基本上就这些。不复杂但容易忽略细节——比如版本匹配、路径冲突、Jakarta 包迁移（Spring Boot 3），配好后文档就活了，改接口、加注释，页面实时更新。
