还在用 Knife4j？试试 Knife4j Next

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

很多团队不是不会用 Swagger UI 或 springdoc-openapi，而是已经习惯了 Knife4j 这一套：接口分组、参数说明、在线调试、全局参数、鉴权、离线导出，以及启动后直接打开的 /doc.html。对国内不少业务团队来说，它比“生成一份 OpenAPI JSON”更贴近日常。

麻烦在于 Spring 生态这几年一直在动：Boot 2.7 → 3.x → 4.x，Jakarta 命名空间，springdoc 1.x / 2.x / 3.x，Gateway 也跟着换代。文档工具一旦跟不上，就会从顺手的东西，变成升级时绕不开的包袱。

Knife4j Next 就是在这个背景下继续维护的社区 fork：源自 Knife4j，目标很克制——保留熟悉的 doc.html 体验，把还在用的 Boot 版本线继续撑住，而不是重做一个“更现代但迁移成本巨大”的新产品。

当前稳定版是 5.0.16，Maven 坐标在 com.baizhukui。

先看现在的界面

OpenAPI3 主线已经切到 React + Vite 前端。观感和交互比旧印象里的传统 Swagger 页舒服不少，但工作流还是那套：看文档、调接口、看响应。

文档首页和接口分组：

Knife4j Next OpenAPI 文档概览

接口详情：参数、响应结构、模型说明：

Knife4j Next 接口文档详情

在线调试：

Knife4j Next 在线调试

迁移通常只改 groupId

我对这个 fork 的定位一直是：延续，不是推倒重来。

多数从 upstream 迁过来的项目，下面这些都可以不动：

访问入口仍是 /doc.html
/v2/api-docs、/v3/api-docs 路径兼容
Java 包名仍是 com.github.xiaoymin.knife4j.*
knife4j.* 配置键兼容
@ApiOperationSupport、@ApiSupport 等注解继续可用

真正要改的，主要是 Maven 坐标。

Spring Boot 3.x（最常见的 upstream 迁移场景）：

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

Spring Boot 4.x：

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

把原来的 com.github.xiaoymin 换成 com.baizhukui，选对 starter，启动后打开 /doc.html 验证即可。业务代码、注解 import、配置键通常不用大改——更像一次依赖替换，而不是架构迁移。回滚也相对简单。

最小配置仍然可以只开开关：

1 2	knife4j: enable: true

访问：

1	http://localhost:8080/doc.html

迁完后建议顺手核对几项：

mvn dependency:tree 里没有残留 com.github.xiaoymin:knife4j-*
/doc.html 能打开
/v3/api-docs（或 OAS2 的 /v2/api-docs）内容正常
若开了 knife4j.production / knife4j.basic，上线前做一次黑盒验证
若依赖旧 Vue UI 的特殊能力，先对照文档看新前端是否覆盖

完整步骤见：从 upstream 迁移。

按版本线选 starter，不要混用

API 文档工具看着是前端页，真正容易踩坑的是后端依赖组合。Boot 2 / 3 / 4 对应的 springdoc 大版本不同，所以 Next 按技术线拆 starter，而不是硬塞进一个“万能包”。

场景	artifactId
Boot 2.x + Springfox / Swagger2（OAS2）	`knife4j-openapi2-spring-boot-starter`
Boot 2.x + springdoc / OpenAPI3	`knife4j-openapi3-spring-boot-starter`
Boot 3.x + Jakarta / OpenAPI3	`knife4j-openapi3-jakarta-spring-boot-starter`
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 2 / 3 / 4	`knife4j-aggregation-*-spring-boot-starter`

Boot 4 单独做了 boot4 starter，而不是复用 Boot 3 的 Jakarta 坐标。依赖线分开，老项目不会被新依赖硬拖走，新项目也能跟上 Framework 7 / springdoc 3.x。

这些不是“文档里写了兼容就算兼容”。仓库里有 smoke tests，覆盖 Boot 2.7 的 OAS2/OAS3、Boot 3.4 / 3.5 Jakarta、Boot 4 WebMVC / Gateway / 独立聚合，以及部分 WebFlux 组合。细节矩阵见：兼容矩阵。

OpenAPI2 只做兼容，OpenAPI3 才是主线

仓库里前端是两条线，边界要先说清楚：

线	源码	UI	策略
OpenAPI3	`front/ui-react`	React	主线：新功能、调试体验、UX
OpenAPI2	`front/vue3`	Vue 3	兼容维护：回归、安全、显示 bug；不扩功能

还在 Boot 2.x + Springfox 的项目，可以用 OAS2 starter 先稳住；已经在 Boot 3.x，或准备上 Boot 4，建议直接走 OpenAPI3 starter。OAS2 新功能请求默认不接，会引导迁 OAS3——不是为了追新，而是 Springfox / OAS2 这条生态本身已经在收缩。

也正因为前端换代，有些 Vue 时代的能力（自定义首页、afterScript、部分旧导出路径等）不保证在 React 新 UI 里原样可用。Next 的策略是写清楚覆盖范围，而不是假装“历史功能全迁完了”。工具迁移最怕的不是少一两个边角，而是文档写全支持、迁完工作流才断。