还在用 Knife4j？试试 Knife4j Next

如果你做过 Java 后端项目，大概率见过 doc.html。

很多团队不是不知道 Swagger UI，也不是不会用 springdoc-openapi，而是已经习惯了 Knife4j 这套更适合国内团队的接口文档体验：接口分组、参数说明、在线调试、全局参数、鉴权配置、离线文档导出，以及那个启动后直接访问的 /doc.html。

问题在于，Java 生态这几年变化很快。

Spring Boot 2.7、Spring Boot 3.x、Jakarta namespace、springdoc-openapi 2.x，再到 Spring Boot 4.x 和 Spring Framework 7，这些变化都在持续推着项目升级。一个 API 文档工具如果不能跟上这些版本线，就会慢慢从“顺手的开发工具”变成“升级时绕不开的历史包袱”。

这也是我维护 Knife4j Next 的原因。

它不是一个全新项目，而是 Knife4j 的社区维护 fork。目标也不玄乎：让已经熟悉 Knife4j 的团队，继续保留 doc.html 的使用习惯，同时把 Spring Boot 2.7 / 3.x / 4.x 这些现实版本线继续维护下去。

先看现在的界面

Knife4j Next 不是只换了 Maven 坐标。OpenAPI3 主线已经接入 React + Vite 新前端，页面观感和交互都比旧印象里那种传统 Swagger 页面舒服很多。

这是文档首页和接口分组概览：

Knife4j Next OpenAPI 文档概览

接口详情页更适合阅读参数、响应结构和模型说明：

Knife4j Next 接口文档详情

在线调试也保留了 Knife4j 最常用的工作流：在文档页里直接构造请求、预览请求、查看响应。

Knife4j Next 在线调试

对很多后端团队来说，这种“文档能看，接口能调”的一体化体验，比单纯生成一份 OpenAPI JSON 更重要。

它解决的不是新鲜感，而是延续性

我对 Knife4j Next 的定位一直很明确：它不是要重写一个和原项目没有关系的新东西，而是尽量降低现有用户的迁移成本。

迁移时最关键的几件事都保持不变：

访问入口仍然是 /doc.html
v2/api-docs / v3/api-docs 入口保持兼容
Java 包名仍然是 com.github.xiaoymin.knife4j.*
knife4j.* 配置键保持兼容
@ApiOperationSupport、@ApiSupport 等既有注解继续保留

真正需要改的，主要是 Maven groupId：

<dependency>
    <groupId>com.baizhukui</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>5.0.7</version>
</dependency>

如果你是 Spring Boot 3.x + OpenAPI3 / springdoc 这条线，通常就是把原来的 com.github.xiaoymin 换成 com.baizhukui，版本升到当前稳定版，然后启动应用访问 /doc.html 验证。

这类迁移我最看重的是可回滚。因为业务代码、注解 import、配置键都不需要大改，所以它不是一次架构迁移，更像是一次依赖替换。

兼容性是这类工具的生命线

API 文档工具看起来是前端页面，真正麻烦的地方却经常在后端依赖组合。

Spring Boot 2.x 时代有 Springfox 和 springdoc-openapi 1.x；Spring Boot 3.x 进入 Jakarta 后，要处理 springdoc-openapi 2.x；Spring Boot 4.x 又进入 springdoc-openapi 3.x 和 Spring Framework 7 的组合。

Knife4j Next 现在按不同技术线拆开维护：

场景	推荐 starter
Spring Boot 2.x + Springfox / Swagger2	`knife4j-openapi2-spring-boot-starter`
Spring Boot 2.x + springdoc-openapi / OpenAPI3	`knife4j-openapi3-spring-boot-starter`
Spring Boot 3.x + Jakarta / OpenAPI3	`knife4j-openapi3-jakarta-spring-boot-starter`
Spring Boot 4.x + OpenAPI3	`knife4j-openapi3-boot4-spring-boot-starter`
Spring Cloud Gateway 3.x	`knife4j-gateway-spring-boot-starter`
Spring Cloud Gateway 5 / Boot 4.x	`knife4j-gateway-boot4-spring-boot-starter`

这也是为什么 Boot 4 没有直接复用 Boot 3 的 Jakarta starter，而是单独做了一条 boot4 starter。依赖线分开，老项目不会被新依赖强行拖着走，新项目也能跟上 Spring Boot 4。

目前项目里有 smoke tests 覆盖 Boot 2.7 的 OAS2/OAS3、Boot 3.4 / 3.5 Jakarta、Boot 4 WebMVC 和 Boot 4 Gateway 等组合。对一个文档增强工具来说，这些验证比“理论上兼容”更有意义。

OpenAPI2 兼容维护，OpenAPI3 继续往前

Knife4j Next 里有两条前端线，最好提前说清楚。

OpenAPI2 / Springfox 这条线使用本仓库里的 Vue3 UI，目标是兼容维护。它适合还没迁出 Springfox 的老项目，重点是保持能用、修回归，不会再追求大量新功能。

OpenAPI3 这条线使用 React + Vite 新前端，是后续主线。新 UI 已经覆盖接口文档、在线调试、模型展示、鉴权配置、离线导出、国际化等常见场景，也会继续补齐体验细节。

这意味着，如果你的项目还在 Spring Boot 2.x + Springfox，可以先用 OpenAPI2 starter 平稳过渡；如果你已经在 Spring Boot 3.x 或准备升级到 Boot 4，建议直接走 OpenAPI3 starter。

这不是为了追新，而是因为 Java 生态本身已经在往 OpenAPI3、Jakarta 和新版本 Spring 迁移。

60 秒迁移方式

以 Spring Boot 3.x 项目为例，先替换依赖：

<dependency>
    <groupId>com.baizhukui</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>5.0.7</version>
</dependency>