Spring Boot 3.x 集成 Knife4j 必须基于 SpringDoc（OpenAPI 3.0），使用 knife4j-openapi-ui 和 springdoc-openapi-starter-webmvc-ui 依赖，访问地址为 /doc.html；需清理 springfox 等旧依赖，配置注解如 @Operation、@Parameter、@Schema 并放行 Security 路径。
Spring Boot 集成 Swagger 或 Knife4j 本质是让项目自动解析 Controller 接口，生成符合 OpenAPI 规范的 JSON 描述，并提供可视化界面。Knife4j 是更推荐的选择——它不是独立框架，而是基于 Swagger（2.x）或 SpringDoc（3.x）的 UI 增强层，中文友好、功能丰富、配置简洁。
选对底层：Swagger2 还是 SpringDoc？
关键看 Spring Boot 版本：
-
Spring Boot 2.x（如 2.7.x）：用
springfox-swagger2+knife4j-spring-boot-starter（v3.x/v4.x），底层仍是 Swagger2 规范。 -
Spring Boot 3.x（含 3.0+）：必须用
springdoc-openapi-starter-webmvc-ui+knife4j-openapi-ui，底层是 OpenAPI 3.0，基于 Jakarta EE，不再兼容 springfox。
注意：Swagger2 已停止维护，新项目强烈建议直接采用 SpringBoot 3.x + SpringDoc + Knife4j 组合。
Spring Boot 3.x 集成 Knife4j（推荐方式）
只需三步，无需写配置类：
Java注释规范Skills
下载
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
- 添加依赖（Maven）：
<dependency><groupid>org.springdoc</groupid><artifactid>springdoc-openapi-starter-webmvc-ui</artifactid><version>2.5.0</version></dependency><dependency><groupid>com.github.xiaoymin</groupid><artifactid>knife4j-openapi-ui</artifactid><version>4.6.0</version></dependency>
- 启用注解（主启动类或任意配置类上加）：
@OpenAPIDefinition可选，用于定义标题、版本等基本信息。 - 启动应用后，访问
http://localhost:8080/doc.html即可打开 Knife4j 中文界面。
接口文档要“看得清”，得加注解
仅靠自动扫描只能显示基础路径和方法，要让参数、返回值、说明清晰可见，需在 Controller 层补充 OpenAPI 注解：
-
@Operation(summary = "用户登录", description = "根据账号密码获取 token")—— 描述接口用途 -
@Parameter(name = "username", description = "用户名", required = true)—— 标明路径/查询参数 -
@Schema(description = "登录响应体")+@io.swagger.v3.oas.annotations.media.Schema—— 修饰 DTO 类字段 - 对请求体（
@RequestBody）自动识别，但建议 DTO 字段加上@Schema注释说明
常见问题与处理
集成后打不开页面或 404，通常有这几个原因：
- 用了 Spring Security：需放行
/doc.html、/swagger-resources/**、/v3/api-docs/**、/webjars/** - 路径不对：SpringBoot 3.x 默认地址是
/doc.html，不是/swagger-ui.html - 没生效：确认是否引入了
-ui后缀的 starter（如springdoc-openapi-starter-webmvc-ui），纯core依赖不带界面 - 中文乱码或样式错乱：检查是否引入了重复的 Swagger 相关依赖（如旧版 springfox），务必清理干净
