Knife4j：实时接口文档的利器

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

Knife4j 的核心优势总结：

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

05 小结

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

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