产品介绍

knife4j-next 是 xiaoymin/knife4j 的社区维护 fork，延续 doc.html 的接入习惯与 starter 模块结构，在 upstream 发布节奏放缓时接续安全修复、兼容性修复和发布流程。

与 upstream 的关系

迁移的最小单位是改 groupId，业务代码、配置键、访问路径都不必动。 详见迁移指引。

兼容性修复。upstream 对 Spring Boot 3.4 / 3.5 的适配步伐变慢，fork 已经升级 springdoc-openapi-jakarta 到 2.8.9，并通过 smoke-tests 覆盖 Boot 2.7.18 的 OAS2/OAS3、Boot 3.4.x/3.5.x Jakarta 与 Boot 4.0.8 Jakarta/Gateway/独立聚合组合。
安全修复。修复了 /v2/api-docs;xxx 分号绕过 Basic 认证的漏洞（#886），以及 gateway context-path 下聚合 host 少斜杠的问题（#954）。
可重复发布流程。.github/workflows/release.yml 通过 Central Publishing Plugin 直接推送 Maven Central，不依赖人工临场操作。
可试用的 Demo。knife4j-demo-openapi3（Spring Boot 4.0 + OpenAPI 3 + React UI）和 knife4j-demo-openapi2（Spring Boot 2.7 + OpenAPI 2 + Vue 3 UI）两个示例工程都附带 Dockerfile，可分别本地运行或在线预览。

下表仅列 master 已合并 的工作，不是路线图承诺。

方向	已合并	对应资料
Boot 2.7.18 starter + UI webjar	✅	快速开始
Boot 3.4.x / 3.5.x 兼容	✅	smoke-tests 模块 `boot3-jakarta-app`、`boot35-jakarta-app`、`boot35-gateway-webmvc-app`
Boot 4.0.8 WebMVC starter	✅	smoke-tests 模块 `boot4-jakarta-app`
Boot 4.0.8 Gateway starter	✅	smoke-tests 模块 `boot4-gateway-app`
Boot 3.5 Gateway Server Web MVC starter	✅	smoke-tests 模块 `boot35-gateway-webmvc-app`
Boot 4.0.8 独立聚合 starter	✅	smoke-tests 模块 `boot4-aggregation-app`
/doc.html 分号绕过修复	✅ `#886`	发布说明
Gateway context-path 修复	✅ `#954`	Gateway 接入
React + Vite 新前端 webjar	✅	在 `knife4j-openapi3-ui` 生效；`knife4j-openapi2-ui` 交由本仓库 `front/vue3` 维护
设置面板（Authorize / GlobalParam / OfflineDoc）	✅	新前端右上角入口
`knife4j-demo-openapi3` / `knife4j-demo-openapi2` Docker 镜像	✅	Demo 预览
`com.baizhukui` 坐标发布	✅	Maven Central

upstream 文档里列出的增强特性在本 fork 的实际实现状态，前端和后端存在差异：

情况	示例	建议
服务端能力已覆盖	`knife4j.enable`、`knife4j.production`、`knife4j.basic`、JSR303 透传	安心使用
Springfox 专属增强在 OAS3 中不处理	`@DynamicParameters`、`@DynamicResponseParameters`、`@ApiOperationSupport(ignoreParameters/includeParameters)` 等	迁到 OpenAPI3 时改用实体类或标准 OpenAPI 注解替代
后端实现，新 React 前端已读取部分默认值	`knife4j.setting.language`、`enable-debug`、`enable-search`、`enable-open-api`、`enable-host`、`enable-group`、`enable-footer`、`enable-footer-custom`、`footer-custom-content`、`enable-request-cache`、`enable-home-custom`、`home-custom-location`、`swagger-model-name` 等	这些是 UI 开关，不替代后端安全控制；本地设置面板选择优先
React UI 已补齐或重做	OAuth2 四种 flow 基础鉴权、HTML/Word/Markdown/OpenAPI JSON 离线导出、`tags-sorter` / `operations-sorter`、`x-openapi.x-markdownFiles` 自定义文档、自定义 Footer、自定义首页、基础 JS/TS 代码片段	优先以本仓库文档和实际 demo 为准
仍未覆盖	afterScript、调试后刷新变量（`enable-reload-cache-parameter`）	这些能力在 Vue2 基线与 Vue3 端口中存在，React 尚未覆盖。三端都没有独立的 Postman Collection 导出器；OpenAPI 复制/下载才是真实能力

这一点最容易混淆，先说清：

UI webjar	打包的前端	对应 starter
`knife4j-openapi2-ui`	本仓库 `front/vue3` 构建产物（兼容维护；能力对齐 Vue2，不是新的功能基线）	`knife4j-openapi2-spring-boot-starter`、`knife4j-aggregation-spring-boot-starter`
`knife4j-openapi3-ui`	React 新前端（从 Preview 起集成，为主线）	`knife4j-openapi3-spring-boot-starter`、`knife4j-openapi3-jakarta-spring-boot-starter`、`knife4j-openapi3-boot4-spring-boot-starter`、`knife4j-aggregation-jakarta-spring-boot-starter`、`knife4j-aggregation-boot4-spring-boot-starter`、`knife4j-gateway-spring-boot-starter`、`knife4j-gateway-webmvc-spring-boot-starter`、`knife4j-gateway-boot4-spring-boot-starter`

所以：

用 Springfox + OpenAPI2 走 openapi2-starter，UI 是本仓库 front/vue3 的构建产物（兼容维护），目标是对齐 upstream Vue2 已有能力，而不是扩张新功能。
用 springdoc-openapi + OpenAPI3 走 openapi3-starter、openapi3-jakarta-starter 或 Boot4 专用 starter，UI 是 新 React 版本（覆盖见上表），不熟悉行为请同时参考 FAQ。

knife4j-next 从 5.0.0 起采用独立 SemVer 版本号，与上游 knife4j 版本号无关：

Patch（5.0.1、5.0.2、5.0.3、5.0.4、5.0.5、5.0.6、5.0.7、5.0.8、5.0.9、5.0.10、5.0.11、5.0.12、5.0.13、5.0.14、5.0.15、5.0.17、5.0.18、5.2.1、5.2.3、5.2.4、5.3.1、5.3.2、5.3.3、5.6.1、5.7.1、5.7.2、5.7.3、5.7.4、5.7.5、5.7.6、5.7.7）：安全修复、Bug 修复与兼容体验改进。
Minor（5.1.0、5.2.0、5.3.0、5.4.0、5.5.0、5.6.0、5.7.0）：前端体验改动、新功能（向后兼容）。
Major（6.0.0）：破坏性变更。

版本号表达变化类型，不代表固定发布日期或响应 SLA。哪些版本和模块仍受支持、哪些兼容面会被保留，以及什么才算一次完整发布，请以仓库的维护政策为准。安全问题请通过安全政策中的私密入口报告，不要先在公开 issue 披露利用细节。