当前位置：首页 > backend >正文

Knife4j：实时接口文档的利器

backend 2025/8/10 21:14:49

01 引言

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

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

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

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

02 Knife4j 简介

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

核心定位：

Knife4j 是一个基于 Swagger（OpenAPI 2.0 / 3.0 规范）的、功能强大的 API 文档增强解决方案和生成工具。
核心价值：

它在完全兼容原生 Swagger 注解和配置的基础上，提供了一个功能更丰富、界面更美观、操作更便捷的前端 UI 界面。
出身：

由国内开发者开源并维护，对中文环境有良好的支持。
本质：

你可以将其理解为 Swagger 的一个超级皮肤和功能扩展包。它替换了默认的 swagger-ui，提供了一套更强大的界面和额外的实用功能。

官网地址：https://doc.xiaominfo.com/

Github地址：https://github.com/xiaoymin/knife4j

Gitee地址：https://gitee.com/xiaoym/knife4j

03 使用

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

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

3.1 Maven依赖

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

3.2 `Knife4j`配置

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {@Bean(value = "knife4jConfiguration")public Docket knife4jConfiguration() {//指定使用Swagger2规范Docket docket=new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder()//描述字段支持Markdown语法.description("# Knife4j RESTful APIs")// API的服务条款.termsOfServiceUrl("https://github.com/simonking-ws")// 作者.contact("wsapplyjob@163.cmo")// 版本.version("1.0").build())//分组名称.groupName("Knife4j 接口文档测试服务").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.simonking.boot.mybaits.controller")).paths(PathSelectors.any()).build();return docket;}
}

3.3 创建接口类

@Api(tags = "Knife4j首页模块")
@RestController
@RequestMapping("/knife4j")
public class Knife4jController {@ApiImplicitParam(name = "userId",value = "用户ID")@ApiOperation(value = "接口测试01")@GetMapping("/test01")public String test01(String userId) {return "test01_" + userId;}@ApiImplicitParams({@ApiImplicitParam(name = "userId",value = "用户ID"),@ApiImplicitParam(name = "orderId",value = "订单")})@ApiOperation(value = "接口测试02")@GetMapping("/test02")public ResponseEntity<UserInfo> test02(String userId, Integer orderId) {return ResponseEntity.ok(new UserInfo());}@ApiOperation(value = "接口测试03")@GetMapping("/test03")public ResponseEntity<String> test03(UserInfo userInfo) {return ResponseEntity.ok("success");}
}

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

@Api：用来标记当前接口的名称或者功能，属性tags指定左侧列表的名称（后面会展示）
@ApiOperation：指定接口的操作的名称
@ApiImplicitParam：指定参数的说明
@ApiImplicitParams：多参数的指定，里面由多个@ApiImplicitParam组成。
@ApiParam：作用在字段上和@ApiImplicitParam功能一致，用作对象的字段

3.4 生成接口文档

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

访问地址：http://localhost:8080/doc.html

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

3.5 接口文档功能

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

① 文档：

接口文档，包括请求参数、响应状态、响应参数以及响应示例。响应示例不支持Mock数据，不是太友好。

如对象的返回：
② 调试：

直接进行接口调试
③ Open：

Knife4j的相关Open接口。
④ Script：

将接口转化成JS、TS脚本

3.6 其他功能

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

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 管理