spring boot集成knife4j生成接口文档只需三步：加依赖（sb2用knife4j-spring-boot-starter，sb3用knife4j-openapi3-jakarta-spring-boot-starter）、写配置类（定义docket或groupedopenapi控制扫描范围与元信息）、加注解（@api、@apioperation等提升文档可读性与调试能力）。
Spring Boot 项目中集成 Swagger 或 Knife4j 自动生成接口文档，核心就三步：加依赖、写配置、加注解。Knife4j 是 Swagger 的增强版，UI 更友好、功能更全（如导出 PDF/Markdown、分组管理、接口排序），推荐直接用 Knife4j，尤其适合国内团队。
一、选对依赖（按 Spring Boot 版本区分）
版本兼容很关键，不能混用：
-
Spring Boot 2.x（JDK 8+）：用
knife4j-spring-boot-starter，它已内置 Swagger2 依赖，无需再单独引入 springfox。 -
Spring Boot 3.x（JDK 17+）：必须用
knife4j-openapi3-jakarta-spring-boot-starter，因为 SB3 全面转向 OpenAPI 3 规范，旧版 Swagger2 不兼容。
示例（SB 2.7.x）：
<dependency><groupid>com.github.xiaoymin</groupid><artifactid>knife4j-spring-boot-starter</artifactid><version>4.5.0</version></dependency>
二、配好配置类（控制文档范围和元信息）
配置类告诉 Knife4j “扫哪些包”“叫什么名字”“显示什么描述”。常用方式是定义一个 @Bean 返回 Docket（SB2）或 GroupedOpenApi（SB3）。
- 扫描路径建议用
RequestHandlerSelectors.basePackage("com.xxx.controller")，避免误扫工具类或测试类。 - 可定义多个
Docket或GroupedOpenApi实现接口分组，比如 “用户端”“管理端”“小程序端”，每组对应不同包路径和 groupName。 - 标题、作者、版本等信息通过
ApiInfoBuilder（SB2）或Info（SB3）设置，前端看到的就是这些内容。
三、补上注解（让文档有描述、有结构）
光有配置只能列出接口，要让文档可读、可调试，得在代码里加注解：
-
@Api加在 Controller 类上，说明这个类是一组接口的集合； -
@ApiOperation加在方法上，描述该接口用途，比如 “根据ID查询用户”； -
@ApiParam加在参数上（尤其@RequestParam和@PathVariable），说明参数含义和是否必填； - 实体类字段用
@ApiModelProperty注释，生成的请求/响应模型才带说明。
不加注解也能出文档，但全是 /user/get?id=xxx 这样的裸路径，没有业务语义，对前端几乎无用。
四、访问与验证（确认生效）
启动项目后，直接浏览器访问：
- SB2 + Knife4j：打开
http://localhost:8080/doc.html（不是 /swagger-ui.html）； - SB3 + Knife4j：同样访问
/doc.html，底层已对接 springdoc-openapi； - 如果页面空白或 404，请检查是否漏了
@EnableKnife4j（SB2）或是否静态资源被拦截（需确认 WebMvcConfigurer 中未 exclude/**/doc.html等路径）。
看到清晰分类、可点击调试、参数带说明的界面，就说明集成成功了。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
