1. 什么是 Knife4j？
Knife4j 是一款基于 Swagger（OpenAPI）的 API 文档增强工具，专为 Java 开发者设计，尤其深度适配 Spring Boot 和 Spring Cloud 生态。它在前端 UI 界面、离线文档导出、接口调试体验等方面对原生 Swagger-UI 进行了大幅增强和优化，是目前国内 Java 社区中最受欢迎的 API 文档生成与调试工具之一。
2. 核心特性与优势
相较于原生 Swagger-UI，Knife4j 提供了更符合国内开发者习惯的强大功能：
- 更美观强大的 UI 界面：提供多主题切换、接口分组树形展示、全局参数设置、离线文档下载等。
- 增强的接口调试功能：支持文件上传、接口响应结果格式化（JSON/XML）、全局请求头/参数管理。
- 离线文档导出：支持将文档一键导出为 Markdown、HTML、Word、PDF 等多种格式，便于离线阅读和交付。
- OpenAPI 3.0 支持：全面支持 OpenAPI 3.0 规范，同时兼容 2.0。
- 微服务聚合：在 Spring Cloud 微服务架构下，支持将多个服务的文档聚合到一个界面中统一查看和调试。
- 安全性增强：支持文档访问权限控制，可配置登录认证。
3. 快速入门：Spring Boot 集成
以下是在 Spring Boot 项目中集成 Knife4j 的基本步骤。
3.1 添加依赖
在项目的pom.xml文件中添加 Knife4j 的 Spring Boot Starter 依赖。
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-spring-boot-starter</artifactId> <version>4.5.0</version> </dependency>注意：如果你使用的是 Spring Boot 2.x 和 Swagger 2.x，请使用knife4j-spring-boot-starter依赖。
3.2 基础配置
在application.yml或application.properties中进行简单配置。
# application.yml 示例 spring: mvc: pathmatch: matching-strategy: ant_path_matcher # 解决 Spring Boot 2.6+ 与 Swagger 的兼容问题 knife4j: enable: true setting: language: zh_cn 生产环境建议关闭文档，可通过配置动态控制 production: false3.3 创建配置类
创建一个 Java 配置类来定义 Docket Bean，这是 Swagger/OpenAPI 的核心配置。
import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class Knife4jConfig { @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("项目 API 文档") .version("1.0") .description("这是一个基于 Spring Boot 和 Knife4j 的 API 文档示例") .contact(new io.swagger.v3.oas.models.info.Contact() .name("开发者") .email("dev@example.com"))); } }3.4 访问文档
启动 Spring Boot 应用后，可以通过以下两个地址访问文档：
- Knife4j 增强 UI：http://localhost:8080/doc.html
- 原生 OpenAPI 规范 JSON：http://localhost:8080/v3/api-docs
打开doc.html即可看到功能丰富的 Knife4j 文档界面。
4. 常用注解与 API 描述
Knife4j 完全兼容 Swagger/OpenAPI 注解，通过在 Controller 和 Model 上使用注解来生成详细的 API 文档。
import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/user") @Tag(name = "用户管理", description = "用户相关的增删改查接口") // 接口分组标签 public class UserController { @GetMapping("/{id}") @Operation(summary = "根据ID查询用户", description = "通过用户ID获取用户详细信息") public User getUser(@PathVariable @Parameter(description = "用户ID", required = true) Long id) { // ... 业务逻辑 return new User(); } @PostMapping @Operation(summary = "创建用户") public User createUser(@RequestBody @Parameter(description = "用户信息", required = true) User user) { // ... 业务逻辑 return user; } }import io.swagger.v3.oas.annotations.media.Schema; @Schema(description = "用户实体") public class User { @Schema(description = "用户ID", example = "1001") private Long id; @Schema(description = "用户名", example = "张三") private String name; @Schema(description = "年龄", example = "25") private Integer age; // ... getters and setters }5. 高级功能与最佳实践
5.1 接口分组（多Docket）
对于大型项目，可以将接口按模块分组展示。
@Bean @Primary public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("public-apis") // 分组名称 .pathsToMatch("/api/public/**") .build(); } @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("admin-apis") .pathsToMatch("/api/admin/**") .build(); }5.2 生产环境安全
建议通过 Profile 或配置中心动态控制文档的开启与关闭。
knife4j: enable: ${knife4j.enable:false} # 默认关闭，通过环境变量开启 production: ${knife4j.production:true} # 生产环境设置为 true 会隐藏文档5.3 离线文档导出
在 Knife4j 的 UI 界面右上角，点击“离线文档”按钮，可以选择导出为 Markdown、HTML、Word 等格式，方便项目交付和归档。
6. 总结
Knife4j 极大地提升了 Spring Boot 项目 API 文档的生成、阅读和调试体验。它弥补了原生 Swagger-UI 在易用性和功能上的不足，并通过丰富的增强特性成为 Java 后端开发的事实标准工具之一。掌握 Knife4j 的使用，能够让你的项目文档更加专业、高效，并改善前后端协作流程。
