Spring Boot 项目怎么集成 Swagger 生成文档-java教程-PHP中文网

spring boot 集成 swagger 推荐使用 springdoc openapi（swagger 3），需添加 springdoc-openapi-starter-webmvc-ui 依赖，零配置即可访问 /swagger-ui.html；通过 openapi bean 或 application.yml 自定义元信息；用 @tag、@operation 等注解增强文档可读性；生产环境应禁用 ui 并考虑权限控制。

spring boot 项目怎么集成 swagger 生成文档

Spring Boot 项目集成 Swagger 生成文档，核心是选对版本、加对依赖、配好配置、再用注解补充说明。当前主流推荐使用 SpringDoc OpenAPI（即 Swagger 3），它原生支持 Spring Boot 2.6+ 和 3.x，无需额外注解即可自动扫描接口，比老旧的 Springfox 更稳定、更轻量、适配性更好。

选对依赖：优先用 springdoc-openapi

避免使用已停止维护的 springfox-swagger2（尤其在 Spring Boot 3+ 中会报错）。Maven 项目直接在 pom.xml 中添加：

springdoc-openapi-starter-webmvc-ui：含 UI 界面 + OpenAPI 文档生成能力
（可选）springdoc-openapi-starter-webflux-ui：如用 WebFlux

示例（Spring Boot 3.x + JDK 17）：

<dependency><groupid>org.springdoc</groupid><artifactid>springdoc-openapi-starter-webmvc-ui</artifactid><version>2.5.0</version></dependency>

基础配置：零代码也能跑起来

SpringDoc 默认自动生效，启动后访问 http://localhost:8080/swagger-ui.html 即可看到文档界面。如需自定义标题、描述、版本等信息，新建一个配置类：

Java注释规范Skills

当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。

下载

创建 @Configuration 类，返回 OpenAPI Bean
通过 new Info().title("xxx").description("xxx").version("1.0") 设置元数据
无需 @EnableSwagger2 或 Docket —— 这些是 Springfox 的旧写法

常见配置项还可写在 application.yml 中：

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    enabled: true

增强可读性：用注解补充关键信息

SpringDoc 能自动识别 @RestController、@GetMapping 等基础注解，但要让文档更专业，建议补充以下注解：

@Tag(name = "用户管理", description = "用户增删改查接口") → 加在 Controller 类上，用于分组和说明
@Operation(summary = "根据ID查询用户", description = "返回完整用户信息") → 加在方法上
@Parameter(description = "用户唯一ID", required = true) → 加在参数前（如 @PathVariable Long id）
@Schema(description = "用户邮箱", example = "user@example.com") → 加在 DTO 字段上，控制请求/响应模型展示

生产环境注意事项

文档页面不应暴露在生产环境：

在 application-prod.yml 中关闭 UI：springdoc.swagger-ui.enabled=false
或通过 profile 控制启用开关：@ConditionalOnProperty(name = "swagger.enabled", havingValue = "true")
如需权限保护，可结合 Spring Security，在 /swagger-ui.html 和 /v3/api-docs 路径上增加认证拦截