17370845950

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 中添加：

  org.springdoc
  springdoc-openapi-starter-webmvc-ui
  2.3.0 

若用 Spring Boot 2.x，改用：
springdoc-openapi-ui（旧版 starter，如 1.6.14）

启动应用后，默认即可访问：
/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），配好后文档就活了，改接口、加注释，页面实时更新。