别再和 Swagger UI 较劲了！这款 SpringBoot API 文档工具，让我开发效率翻倍

作为一名写了四年 SpringBoot 的后端开发者，我和 Swagger UI 的 “爱恨情仇” 能说上半天。最开始用它时觉得新鲜 —— 不用手动写文档，接口能自动生成；可越用到后面越觉得折磨：找接口要翻半天、调接口得重复填 Token、导出文档还要手动排版……

直到三个月前，同事给我推荐了Knife4j，我才发现：原来 API 文档工具也能这么好用。它像给 Swagger 换了身 “新装”，不仅兼容所有旧注解，还解决了 Swagger UI 的所有痛点。今天就把我的使用体验和集成步骤分享出来，希望能帮你少走弯路。

一、那些年被 Swagger UI 折磨的瞬间

先聊聊我和 Swagger UI 的 “糟心日常”，看看你是不是也感同身受：

1. 找接口像 “在菜市场找菜”

项目里有七八十个接口时，Swagger UI 的界面简直是灾难 —— 所有接口按字母乱序排列，没有清晰分类，想找 “用户登录” 接口，得从 “A” 开头的接口翻到 “U” 开头，有时候翻着翻着还会不小心刷新页面，又得重新来。

2. 调接口像 “重复机械劳动”

我们项目的接口都要带 Token 验证，每次调试新接口，我都得先从登录接口复制 Token，再粘贴到新接口的 Header 里，一天下来要重复几十次。更麻烦的是复杂 JSON 参数，Swagger UI 没有格式化功能，手动换行对齐能花好几分钟。

3. 导文档像 “做手工活”

每次迭代完要给前端发接口文档，我都得打开 Swagger UI，一个接口一个接口地复制地址、参数、响应格式，再粘贴到 Word 里排版，遇到字段多的接口，光整理就要 1 个多小时，还容易漏填参数说明。

如果你也被这些问题困扰过，那 Knife4j 绝对能让你眼前一亮。

二、为什么说 Knife4j 是 “Swagger 的升级版”？

第一次打开 Knife4j 时，我就被它的界面惊艳到了 —— 不是 Swagger UI 那种十年前的老旧风格，而是清爽的现代化设计，还支持暗黑模式。但真正让我放弃 Swagger UI 的，是它的三个核心优势：

1. 零成本迁移，不用改一行旧代码

最香的一点是兼容性！我之前用 Swagger 写的@Api、@ApiOperation、@ApiParam等注解，换成 Knife4j 后完全生效，不用重新写注解、不用改业务逻辑，只需要换个依赖、加几行配置，十分钟就能搞定集成。

对于已经上线的老项目来说，这点太重大了 —— 不用担心迁移成本，也不用怕影响现有功能。

2. 功能全到 “感动”，解决所有痛点

Knife4j 像是把开发者的需求都摸透了，Swagger UI 没有的功能它都有：

接口按 Controller 自动分组，还能自定义排序，找接口一目了然；

支持全局 Token 配置，填一次就能自动带所有接口，不用重复粘贴；

能导出 Markdown/HTML/PDF 格式的文档，不用再手动整理；

调试历史会自动保存，刷新页面也不会丢，重新请求不用再填参数。

3. 细节贴心，用着 “舒服”

除了核心功能，Knife4j 的许多细节都让我觉得 “很懂开发者”：

调试时 JSON 参数会自动格式化，字段多也能看得清清楚楚；

鼠标悬停在参数上，会显示注解里写的说明，不用再翻文档；

支持接口搜索，输入关键词就能快速找到目标接口，不用再翻页。

三、SpringBoot 集成 Knife4j，三步就能搞定

话不多说，直接上实操步骤。不管你用的是 SpringBoot 2.x 还是 3.x，步骤都很简单，代码我都整理好了，复制粘贴就能用。

第一步：换依赖，移除 Swagger，引入 Knife4j

先打开 pom.xml，删掉原来的 Swagger 依赖（列如springfox-swagger2、springfox-swagger-ui），然后添加 Knife4j 的 Starter：

<!– Knife4j API文档 Starter –>

<dependency>

    <groupId>com.github.xiaoymin</groupId>

    <artifactId>knife4j-spring-boot-starter</artifactId>

    <version>3.0.3</version> <!– 推荐3.0.3及以上，兼容性更好 –>

</dependency>

踩坑笔记：SpringBoot 3.x 需要 JDK 17 及以上，如果你用的是 JDK 8，提议用 SpringBoot 2.x，依赖坐标是一样的，不用改。

第二步：写配置，只需十行代码

创建一个 Knife4j 的配置类，主要配置文档的标题、描述、联系人这些基础信息，比 Swagger 的配置简单多了：

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

@Configuration

public class Knife4jConfig {

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.OAS_30) // 兼容OpenAPI 3.0规范

                .apiInfo(new ApiInfoBuilder()

                        .title(“电商项目API文档”) // 改成你的项目名

                        .description(“基于Knife4j生成的API文档，方便前后端协作”) // 文档描述

                        .contact(“你的名字”) // 填自己或团队名

                        .version(“1.0.0”) // 版本号

                        .build())

                .select()

                // 改成你项目中Controller的实际路径

                .apis(RequestHandlerSelectors.basePackage(“com.example.ecommerce.controller”))

                .paths(PathSelectors.any())

                .build();

    }

}

关键提醒：如果是 SpringBoot 3.x，必定要在启动类上加@EnableOpenApi注解，否则文档无法访问；SpringBoot 2.x 不用加这个注解。启动类示例：

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

import springfox.documentation.oas.annotations.EnableOpenApi;

@SpringBootApplication

@EnableOpenApi // SpringBoot 3.x必须加，2.x不用加

public class EcommerceApplication {

    public static void main(String[] args) {

        SpringApplication.run(EcommerceApplication.class, args);

    }

}

第三步：访问文档，体验升级

启动项目后，不用再访问 Swagger UI 的http://localhost:8080/swagger-ui.html，而是打开这个地址：

http://localhost:8080/doc.html

第一次打开时，我差点以为进错了页面 —— 界面清爽，接口按 Controller 分好组，调试框比 Swagger UI 大了一倍，还能一键切换暗黑模式，调接口的心情都变好了。

四、Knife4j 的三个 “宝藏功能”，用了就再也回不去

光有颜值不够，Knife4j 的这三个功能，才真正帮我节省了大量时间，让开发效率提升了至少 30%。

1. 1 分钟导出规范文档，不用再手动整理

之前给前端发文档，我得花 1 小时手动复制粘贴，目前用 Knife4j 的导出功能，1 分钟就能搞定：

点击文档右上角的 “导出” 按钮；

选择 Markdown 格式（前端最喜爱的格式，能直接粘到 Notion 或语雀里）；

勾选要导出的接口（列如 “用户管理接口”“订单管理接口”，支持批量选择）；

点击 “导出”，自动生成带格式的文档，字段说明、响应示例都清清楚楚，直接发前端就行。

2. 全局 Token 配置，一次填写终身受益

这是我最爱的功能！之前每次调接口都要复制粘贴 Token，目前只需配置一次：

点击文档顶部的 “全局参数设置”；

参数类型选 “Header”，参数名填Authorization（或你项目的 Token 参数名）；

参数值填Bearer 你的Token（列如Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…）；

勾选 “自动携带”，后来所有接口调试都会自动带这个 Token，不用再重复填。

3. 调试历史记录，刷新页面也不丢

Swagger UI 最烦的一点是，刷新页面后调试记录全没了，重新调接口要再填一遍参数。Knife4j 会自动保存历史：

调完接口后，点击 “历史” 按钮，能看到之前的请求参数、响应结果、请求时间；

想重新请求，点击 “重新请求”，直接复用之前的参数，不用再手动输入，尤其是复杂参数，能省好几分钟。

五、集成时最容易踩的两个坑，提前避坑

我集成时遇到过两个问题，后来发现许多小伙伴也会踩同样的坑，提前整理了解决方案，帮你省时间。

坑 1：SpringBoot 3.x 访问 /doc.html 报 404

缘由：SpringBoot 3.x 默认禁用了静态资源访问，Knife4j 的页面资源没被放行。

解决方案：创建一个 Web 配置类，手动放行静态资源：

@Configuration

public class WebConfig implements WebMvcConfigurer {

    @Override

    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        // 放行Knife4j的文档页面

        registry.addResourceHandler(“/doc.html”)

                .addResourceLocations(“classpath:/META-INF/resources/”);

        // 放行Knife4j的CSS、JS等静态资源

        registry.addResourceHandler(“/webjars/**”)

                .addResourceLocations(“classpath:/META-INF/resources/webjars/”);

    }

}

坑 2：接口显示不全，有的 Controller 没出现

缘由：配置类里的basePackage路径写错了，没扫到 Controller。

解决方案：

检查RequestHandlerSelectors.basePackage(“你的Controller路径”)，列如你的 Controller 在com.example.ecommerce.controller.user下，路径要写全，不能只写com.example.ecommerce.controller（虽然子包会扫，但怕配置了排除规则）；

实在不确定，就用RequestHandlerSelectors.any()扫描所有接口，排查是否为路径问题（生产环境提议用准确路径，避免扫到冗余接口）。

六、写在最后：好的工具，能让开发少走许多弯路

换 Knife4j 之前，我总觉得 “API 文档工具能用就行”，直到用了它才发现：好的工具不仅能提升效率，还能让开发心情变好。

目前我们团队已经全员用 Knife4j 了，前端同事说 “再也不用催你整理文档了”，测试同事说 “调试接口方便多了”，我自己也不用再花时间做重复工作，能把更多精力放在业务逻辑上。

如果你也被 Swagger UI 折磨过，不妨花十分钟试试 Knife4j，信任你会和我一样，觉得 “早换早香”。

最后想问问大家：你在使用 Swagger UI 时，遇到过最头疼的问题是什么？欢迎在评论区留言，咱们一起交流解决方案～也可以说说你还用过哪些好用的 API 文档工具，下次我也试试！