保持 doc.html 使用习惯
Maven groupId 切到 com.baizhukui 即可替换原依赖，/doc.html、/v2/api-docs、/v3/api-docs 入口保持不变。
迁移指引
Knife4j Next更现代的 Knife4j
延续熟悉的 doc.html 接入方式，持续修复 Spring Boot 2.7 / 3.x / 4.x 的兼容性。这是 Knife4j 的社区维护 fork。
Skip to content
Knife4x Go v0.8.6
Go 服务现在也能嵌入同一套 React UI，通过标准库 net/http Handler 挂载 UI、加载已有 OpenAPI 3 文档并提供调试控制台。查看 Go 接入。
这是 Knife4j 的 fork，不是重写
knife4j-next 是 xiaoymin/knife4j 的社区维护分支。
- 保留
com.github.xiaoymin.knife4j.*Java 包名，不做重命名。 - 保留
doc.html/v2/api-docs/v3/api-docs访问入口。 - 保留
@ApiOperationSupport、@ApiSupport、knife4j.*等全部既有注解与配置键。 - 只改
groupId：com.github.xiaoymin→com.baizhukui，其余业务代码不用动。
60 秒上手
默认推荐 Spring Boot 4.x：
xml
<dependency>
<groupId>com.baizhukui</groupId>
<artifactId>knife4j-openapi3-boot4-spring-boot-starter</artifactId>
<version>5.7.7</version>
</dependency>仍在 Spring Boot 3.x 时：
xml
<dependency>
<groupId>com.baizhukui</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>5.7.7</version>
</dependency>Spring Boot 2.x / Gateway / 独立聚合等场景，将 artifactId 换成对应 starter，见 快速开始。
最小配置（使用 springdoc 默认 /v3/api-docs 和 /swagger-ui.html）：
yaml
knife4j:
enable: trueknife4j.setting.language 默认就是 zh_cn；springdoc.swagger-ui.path 和 springdoc.api-docs.path 也沿用 springdoc 默认值即可。真实项目可按需补充 springdoc.packages-to-scan、paths-to-match 或 swagger-ui.tags-sorter 等扫描与排序配置。
启动应用后访问 http://localhost:8080/doc.html。完整流程见 快速开始。
5.7.7 版本亮点 最新
5.7.7 纳入 Java 依赖维护、共享 React UI 工具链迁移与 WebJar 增量打包修复。OpenAPI 3.1 / 3.2 消费仍从 5.7.0 起提供。同步发布 Knife4x Go v0.8.6。
- Boot4 依赖更新至 Spring Boot 4.0.8 / Spring Cloud 2025.1.3
- 共享 React UI 迁移至 React 19 / Ant Design 6，并适配页签滚动与外部资源面板
- 修复 React WebJar 增量打包残留分块与源码包构建输出清理
完整更新列表见 发布说明。
关于新前端覆盖范围
能力基线是 upstream Vue2（legacy/vue2）。Vue3 与 React 都是维护者重写，各自可能漏掉 Vue2 能力。React 已读取部分 knife4j.setting.*（含自定义 Footer、接口变化提示、请求参数缓存与后端注入的自定义首页 Markdown）；仍缺 afterScript 与调试后刷新变量。三端都没有独立的 Postman Collection 导出器，请使用 OpenAPI 复制/下载。切换前端前先查阅 相对 Vue2 的覆盖范围。home-custom-path 仍由后端读取，不是前端读取文件的入口。knife4j-openapi2-ui 由本仓库 front/vue3 构建，处于 OAS2 兼容维护状态。
文档导航
上手
- 产品介绍：这个 fork 的定位、与 upstream 的对照表
- 快速开始：Spring Boot 2.x / 3.x / 4.x 完整接入
- 迁移指引：从
com.github.xiaoymin切到com.baizhukui - OpenAPI 3.1 支持与迁移：3.1.x 矩阵、JSON Schema 方言、安全边界、迁移示例与有效夹具
- Demo 预览：
knife4j-demo-openapi3（OpenAPI 3）与knife4j-demo-openapi2（OpenAPI 2）两条线的本地跑 / Docker Compose - 常见问题：doc.html 404、生产环境禁用、Nginx 反向代理、React 配置不生效
组件
- Gateway 聚合：Spring Cloud Gateway + knife4j-gateway-starter
- Aggregation 聚合：disk / cloud / nacos / eureka / polaris
- WebFlux 方案：当前 fork 中的 webflux 实际情况与替代路径
参考
- 兼容矩阵：Java、Spring、Boot、springdoc 基线
- 版本参考表：Boot 版本如何选 knife4j 版本
- 模块说明：Maven 模块的职责与选择决策
- 配置参考：全部
knife4j.*YAML 选项 - 注解速查：Springfox 专有 vs 通用注解
其他