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 属于开发调试工具，生产环境必须禁用：

• 方式一：通过配置文件（推荐）

# 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/**）

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南