Knife4j：实时接口文档的利器

在日常开发中，尤其移动端的开发，都需要编写接口文档。你们还是用`WIKI`、`showDoc`、`语雀`等工具写么？

接口的文档的独立编写，维护起来总是变的困难。参数的变化、接口的增加或者删除，小小的改动都需要同步更新接口文档，相当麻烦，甚至不再去维护接口文档，接口文档变成一次性的文档。

有人可能想到`Swagger`，但是`Swagger`的`UI`并不美观。

![](https://doc.xiqi.site/media/202509/2025-09-24_012843_1765780.1315192066849893.webp)

今天介绍一款基于`Swagger`加强版接口文档框架`Knife4j`，美化了`UI`，提高了用户体验。

## 02 Knife4j 简介

`Knife4j` 作为一款专注于增强 Swagger 文档能力的国产开源工具，它极大地提升了开发者的接口文档体验。

![](https://doc.xiqi.site/media/202509/2025-09-24_012843_1842770.917155747705433.webp)

-   **核心定位：**
    
    `Knife4j` 是一个基于 `Swagger`（`OpenAPI` 2.0 / 3.0 规范）的、功能强大的 API 文档增强解决方案和生成工具。
    
-   **核心价值：**
    
    它在完全兼容原生 Swagger 注解和配置的基础上，提供了一个功能更丰富、界面更美观、操作更便捷的前端 UI 界面。
    
-   **出身：**
    
    由国内开发者开源并维护，对中文环境有良好的支持。
    
-   **本质：**
    
    你可以将其理解为 `Swagger` 的一个超级皮肤和功能扩展包。它替换了默认的 `swagger-ui`，提供了一套更强大的界面和额外的实用功能。

官网地址：[doc.xiaominfo.com/](https://link.juejin.cn?target=https%3A%2F%2Fdoc.xiaominfo.com%2F)

Github地址：[github.com/xiaoymin/kn…](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Fxiaoymin%2Fknife4j)

Gitee地址：[gitee.com/xiaoym/knif…](https://link.juejin.cn?target=https%3A%2F%2Fgitee.com%2Fxiaoym%2Fknife4j)

## 03 使用

`Knife4j`在`SpringBoot`中使用非常简单，通过简单的配置，就可以完成。

**注意：**`SpringBoot 2.x`和`SpringBoot 3.x`的依赖是不一样的，集成方式也稍有不同，详情请参考官方文档。本文以`SpringBoot2.x`为例介绍。

### 3.1 Maven依赖

```xml
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi2-spring-boot-starter</artifactId> <version>4.4.0</version>
</dependency>
```

### 3.2 `Knife4j`配置

```java
 public class Knife4jConfig { public Docket knife4jConfiguration() { Docket docket=new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() .description("# Knife4j RESTful APIs") .termsOfServiceUrl("https://github.com/simonking-ws") .contact("wsapplyjob@163.cmo") .version("1.0") .build()) .groupName("Knife4j 接口文档测试服务") .select() .apis(RequestHandlerSelectors.basePackage("com.simonking.boot.mybaits.controller")) .paths(PathSelectors.any()) .build(); return docket;
    }
}
```

### 3.3 创建接口类

```java
 public class Knife4jController { public String test01(String userId) { return "test01_" + userId; } public ResponseEntity<UserInfo> test02(String userId, Integer orderId) { return ResponseEntity.ok(new UserInfo()); } public ResponseEntity<String> test03(UserInfo userInfo) { return ResponseEntity.ok("success");
    }
}
```

说明一下主要的注解参数：

-   `@Api`：用来标记当前接口的名称或者功能，属性`tags`指定左侧列表的名称（后面会展示）
    
-   `@ApiOperation`：指定接口的操作的名称
    
-   `@ApiImplicitParam`：指定参数的说明
    
-   `@ApiImplicitParams`：多参数的指定，里面由多个`@ApiImplicitParam`组成。
    
-   `@ApiParam`：作用在字段上和`@ApiImplicitParam`功能一致，用作对象的字段
    
    ![](https://doc.xiqi.site/media/202509/2025-09-24_012843_1961890.891394520437676.webp)

### 3.4 生成接口文档

接口文档属于在先接口文档，项目启动之后，就可以访问。

访问地址：[http://localhost:8080/doc.html](https://link.juejin.cn?target=http%3A%2F%2Flocalhost%3A8080%2Fdoc.html)

服务器部署的话，将对应的`IP`和端口换成服务器的`IP`和端口即可。

![](https://doc.xiqi.site/media/202509/2025-09-24_012843_2211550.21058996904697092.webp)

### 3.5 接口文档功能

![](https://doc.xiqi.site/media/202509/2025-09-24_012843_2634310.7155720660344871.webp)

接口文档随着项目发布访问会自动更新。

-   ① 文档：
    
    接口文档，包括请求参数、响应状态、响应参数以及响应示例。响应示例不支持Mock数据，不是太友好。
    
    如对象的返回：
    
    ![](https://doc.xiqi.site/media/202509/2025-09-24_012843_2104780.8914092032034934.webp)
    
-   ② 调试：
    
    直接进行接口调试
    
    ![](https://doc.xiqi.site/media/202509/2025-09-24_012843_2392350.6942034103876347.webp)
    
-   ③ Open：
    
    `Knife4j`的相关Open接口。
    
    ![](https://doc.xiqi.site/media/202509/2025-09-24_012843_2613580.32052548870965225.webp)
    
-   ④ Script：
    
    将接口转化成`JS`、`TS`脚本
    
    ![](https://doc.xiqi.site/media/202509/2025-09-24_012843_2488150.7903719606773043.webp)

### 3.6 其他功能

![](https://doc.xiqi.site/media/202509/2025-09-24_012843_2820630.7147560354323652.webp)

在文档管理里面可以设置全局参数，导出离线温度囊以及个性化设置。

## 04 同类产品对比及 Knife4j 优势

| 特性/产品 | Knife4j | 原生 Swagger UI (`swagger-ui`) | Springdoc OpenAPI UI (`swagger-ui`) | Apifox / YAPI / Postman (等独立工具) |
| --- | --- | --- | --- | --- |
| **定位** | **Swagger 文档增强器** | Swagger 官方基础 UI | Swagger 官方基础 UI (Springdoc 集成) | **独立 API 全生命周期管理平台** |
| **核心功能** | **文档展示、增强调试、离线导出等** | 基础文档展示、简单调试 | 基础文档展示、简单调试 | **设计、调试、Mock、自动化测试、文档等** |
| **UI 美观度 & 体验** | **极佳 (现代化，符合国人习惯)** | 基础 | 基础 | 通常较好 (独立开发) |
| **集成复杂度** | **低 (替换依赖即可)** | 低 (默认集成) | 低 (Spring Boot Starter) | **高 (需独立部署/使用)** |
| **在线调试能力** | **强大 (参数处理、响应查看、场景保存)** | 基础 | 基础 | **非常强大 (专业化)** |
| **离线文档导出** | **支持 (Markdown, Word, Html, Pdf)** | 不支持 (需第三方插件或手动) | 不支持 (需第三方插件或手动) | 通常支持 (是其强项) |
| **文档目录/分组** | **支持 (清晰结构)** | 支持 (分组) | 支持 (分组) | 支持 |
| **接口搜索** | **支持 (快速定位)** | 支持 | 支持 | **支持 (高级搜索)** |
| **权限认证 (UI)** | **支持 (Basic, JWT 等)** | 支持 | 支持 | **支持 (更完善)** |
| **Mock 数据** | 有限支持 | 无 | 无 | **核心功能 (强大)** |
| **自动化测试** | 无 | 无 | 无 | **核心功能 (强大)** |
| **代码生成** | 无 | 无 | 无 | 部分支持 |
| **与项目代码紧密度** | **高 (无缝集成，注解驱动)** | 高 | 高 | **低 (独立于代码)** |
| **中文支持** | **原生优秀** | 需配置/不完全 | 需配置/不完全 | 通常较好 |
| **适合场景** | **需要强大文档/调试的 Java Web 项目** | 简单查看文档 | 简单查看文档 (Spring Boot 3+) | **大型团队全流程 API 管理** |

**Knife4j 的核心优势总结：**

-   **无缝增强，开箱即用：** 只需替换一个依赖，即可获得远超原生 Swagger UI 的体验，无需改变已有的 Swagger 注解习惯。
-   **极致易用的文档与调试：** 界面设计美观直观，**在线调试功能极其强大且便捷**，大大提升开发调试效率。
-   **丰富的实用功能：** **离线导出**（满足归档、交付需求）、接口搜索、全局参数、接口排序、登录认证支持等。
-   **对国内开发者友好：** 中文文档完善，社区活跃（Gitee/Github），遇到问题更容易找到解决方案。
-   **轻量级集成：** 作为项目的一部分运行，无需额外部署和维护独立的文档平台。
-   **活跃的开源社区：** 持续迭代更新，修复问题快，新功能跟进及时。

## 05 小结

`Knife4j` 成功解决了原生 `Swagger UI` 在功能性和用户体验上的痛点，为 Java 开发者提供了**近乎完美的 `API` 文档管理和调试体验**。它特别适合那些追求开发效率、重视接口文档质量、且希望以最小成本获得最大提升的团队和个人开发者。

**如果你正在使用 `Swagger` 并对其默认界面感到不满，`Knife4j` 几乎是你无痛升级的最佳选择。** 它能让你和你的团队更愉悦地编写、查看、调试 API，显著提升前后端协作效率。立即尝试 `Knife4j`，体验现代化 `API` 文档的强大魅力！