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 组合。
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
Spring Boot 3.x 集成 Knife4j（推荐方式）
只需三步，无需写配置类：
- 添加依赖（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），务必清理干净
