Knife4j是Swagger的国产增强版，基于OpenAPI 3规范，提供中文UI、离线导出、接口排序等丰富功能；集成需引入springdoc-openapi与knife4j依赖，配置扫描路径并启用UI，生产环境务必禁用。
在 Spring Boot 中集成 Swagger 或 Knife4j 生成接口文档，核心是引入对应依赖、配置扫描路径和启用 UI 界面。Knife4j 是 Swagger 的增强版（国产），界面更友好、功能更丰富（如离线文档导出、调试鉴权支持等），推荐优先使用。
1. 使用 Knife4j（推荐）
Knife4j 基于 Swagger 3（即 OpenAPI 3），需搭配 springdoc-openapi 使用，不兼容旧版 Swagger 2。
- 添加 Maven 依赖（Spring Boot 2.6+ / 3.x）：
<dependency><br> <groupId>org.springdoc</groupId><br> <artifactId>springdoc-openapi-starter-webmvc-api</artifactId><br> <version>2.3.0</version> <!-- 适配 Spring Boot 3；若用 2.6/2.7，选 2.0.x 或 1.6.x --><br></dependency><br><dependency><br> <groupId>com.github.xiaoymin</groupId><br> <artifactId>knife4j-openapi-ui</artifactId><br> <version>4.4.0</version><br></dependency>
- 无需额外 Java 配置类，启动后默认开放：
– 文档地址：http://localhost:8080/swagger-ui.html（兼容旧习惯）
– Knife4j 增强 UI：http://localhost:8080/doc.html - 如需自定义（如分组、标题、描述），可加一个
@Configuration类：
@Configuration<br>public class Knife4jConfig {<br> @Bean<br> public GroupedOpenApi api() {<br> return GroupedOpenApi.builder()<br> .group("v1")<br> .pathsToMatch("/api/**")<br> .build();<br> }<br><br> @Bean<br> public OpenAPI customOpenAPI() {<br> return new OpenAPI()<br> .info(new Info()<br> .title("我的 API 文档")<br> .version("1.0")<br> .description("用户管理与订单服务接口说明")); <br> }<br>}2. 控制接口是否出现在文档中
默认会扫描所有 @RestController 和 @RequestMapping 方法。可通过注解精准控制：
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
-
@Operation(summary = "创建用户", description = "传入用户基本信息")—— 描述接口 -
@Parameter(name = "id", description = "用户ID", required = true)—— 描述单个参数 -
@Schema(description = "用户邮箱", example = "user@example.com")—— 用于 DTO 字段注释 - 隐藏某个接口：在方法上加
@Hidden
3. 生产环境关闭文档（安全必需）
Swagger/Knife4j 属于开发调试工具，生产环境必须禁用：
立即学习“Java免费学习笔记（深入）”；
- 方式一：通过配置文件（推荐）
# application.yml<br>springdoc:<br> api-docs:<br> enabled: false<br> swagger-ui:<br> enabled: false<br>knife4j:<br> enable: false
- 方式二：按 profile 区分（开发启用，生产禁用）
spring:<br> profiles:<br> active: dev<br><br>---<br>spring:<br> profiles: prod<br>springdoc:<br> api-docs:<br> enabled: false<br>knife4j:<br> enable: false
4. 常见问题处理
- 启动报错 “Failed to start bean 'documentationPluginsBootstrapper'”：多因 Spring Boot 版本与 springdoc 版本不匹配，查官方 Compatibility Matrix 选对版本
-
DTO 字段没显示示例值：确保字段加了
@Schema，且类上有@Schema或使用 Lombok 的@Data+@Schema组合 -
Knife4j 页面空白或 404：确认访问的是
/doc.html（不是/swagger-ui/index.html），并检查静态资源是否被拦截（Spring Security 需放行/doc.html、/webjars/**、/v3/api-docs/**）
