路线图
这份路线图不是长期愿景海报，而是围绕最现实的目标排优先级：先成为一个能被社区信任的维护分支，再逐步变成真正的新主线。
当前阶段：5.7.7 与 OpenAPI 3.2
已完成 ✅
| 领域 | 里程碑 | 状态 |
|---|---|---|
| 基础设施 | Maven groupId 迁移至 com.baizhukui | ✅ |
| 基础设施 | GitHub Actions CI/CD 流程补齐 | ✅ |
| 安全 | 修复 /v2/api-docs 分号绕过 Basic 认证（#886） | ✅ |
| 兼容性 | Spring Boot 3.4.x / 3.5.x 兼容（springdoc 2.8.9） | ✅ |
| 兼容性 | Spring Boot 4.x WebMVC 专用 starter（knife4j-openapi3-boot4-spring-boot-starter，springdoc-openapi 3.0.3） | ✅ |
| Bug 修复 | Gateway context-path 导致聚合 host 少斜杠（#954） | ✅ |
| Bug 修复 | Gateway 聚合刷新非默认文档分组深链时恢复正确 group | ✅ |
| Bug 修复 | React UI 对异常 api-docs 响应展示诊断提示 | ✅ |
| 兼容性 | Boot4 + Kotlin is 前缀字段文档命名修复 | ✅ |
| Bug 修复 | OpenAPI3 自定义 springdoc.api-docs.path / swagger-config 发现逻辑修复（#344） | ✅ |
| 服务接口 | /knife4j/config v1 运行时发现接口（schemaVersion + openapi.{apiDocsUrl, swaggerConfigUrl}） | ✅ |
| Demo | knife4j-demo-openapi3（OpenAPI 3）与 knife4j-demo-openapi2（OpenAPI 2）双 demo + Docker 部署 | ✅ |
| 文档 | VitePress 文档站全面重写 | ✅ |
| React 前端 | 基础架构（路由、侧边栏、分组切换、搜索） | ✅ |
| React 前端 | ApiDoc 接口文档展示（参数表格 + 响应结构 + 复制操作） | ✅ |
| React 前端 | ApiDebug 接口调试（类型感知参数输入 + requestBody 多 content-type + cURL 预览 + 响应复制/下载） | ✅ |
| React 前端 | SwaggerModels 数据模型展示 | ✅ |
| React 前端 | Authorize 鉴权配置（securitySchemes 动态渲染 + OAuth2 四种 flow 基础 token 获取/注入） | ✅ |
| React 前端 | GlobalParam 全局参数 | ✅ |
| React 前端 | Home 首页统计概览（重设计） | ✅ |
| React 前端 | 离线文档导出（HTML / Word） | ✅ |
| React 前端 | 真实 API 数据对接（/v3/api-docs） | ✅ |
| React 前端 | 集成到 knife4j-openapi3-ui webjar | ✅ |
| React 前端 | i18n 中英日切换 | ✅ |
| React 前端 | 设置面板（Header 右上角整合） | ✅ |
| React 前端 | Tab 右键菜单 + 刷新后状态持久化 | ✅ |
| React 前端 | 侧边栏接口搜索高亮 + Method 过滤条 | ✅ |
| React 前端 | Markdown 渲染（API/tag/info description） | ✅ |
| React 前端 | OAuth2 四种 flow 的基础鉴权调试 | ✅ |
| React 前端 | 离线文档导出（HTML / Word / Markdown / OpenAPI JSON） | ✅ |
| React 前端 | 尊重后端 tags-sorter / operations-sorter 配置 | ✅ |
| React 前端 | 调试器请求 baseUrl 智能解析（enableHost > OpenAPI servers[0].url > origin） | ✅ |
| React 前端 | 设置面板默认值与后端 starter 对齐，能读取 OpenAPI 文档中的 enableHost 等服务端注入项 | ✅ |
| React 前端 | 调试器 raw body 多格式 Beautify（JSON / XML / HTML / JavaScript）与完整 MIME 展示 | ✅ |
| React 前端 | enableSwaggerModels=false 时 Schema 页以 403 提示填充，路由守卫防止被禁用路径被访问 | ✅ |
| React 前端 | ApiDoc 展示 operation x-author 作者信息 | ✅ |
| knife4j-core | debug 解析层抽取（resolveRef / OperationDebugModel / requestBuilder） | ✅ |
| knife4j-core | buildSchemaExample & buildSchemaFieldTree | ✅ |
| 基础设施 | Bun workspace 统一 front 包管理 | ✅ |
| 基础设施 | Node.js 22 LTS + Prettier + Spotless 格式化规范 | ✅ |
OpenAPI 3.1 里程碑与已知边界
OpenAPI 3.1 按“文档加载 → SchemaEngine → 展示与调试 → 受控资源图 → 可移植交付 → 真实 springdoc 验证”的顺序完成核心链路，保持 OpenAPI 3.0.x 与 OAS2 兼容路径不变。
| 范围 | 状态 | 契约 |
|---|---|---|
| OpenAPI 3.1.x | ✅ | 各 patch 使用同一 feature set 与安全边界；离线导出复用统一版本判断 |
| JSON Schema Draft 2020-12 | ✅ | OAS Base Dialect、标准词汇、字段树、示例与请求/响应诊断 |
| 未知关键字 opaque 载荷 | ✅ | 资源声明预扫描只进入已知 Schema 位置；普通载荷内保留名不参与资源或 anchor 注册（#743） |
| 外部 Schema 资源 | ✅ | 默认拒绝、精确 URI 授权、无凭据请求、固定预算、可撤销 |
| 可移植交付 | ✅ | 单接口 JSON 闭包、变化指纹、HTML / Markdown / DOC / DOCX 离线快照 |
| springdoc 端到端 | ✅ | Boot 3 WebMVC/WebFlux 显式 3.1；Boot 4 WebMVC 默认/显式 3.1；Boot 2 保持 3.0 |
| OpenAPI 3.2.x | ✅ | 按 3.2 语义消费，不按 3.1 猜测处理；从 Java 5.7.0 / Go v0.8.0 起发布。见 OpenAPI 3.2 支持矩阵 |
支持矩阵、浏览器限制、迁移示例和最小有效夹具统一收录在 OpenAPI 3.1 支持与迁移。这一里程碑从 Java 5.5.0 起提供，Knife4x Go 版本单独发布。 父路线图 #699 所列实现、端到端与文档子项已收敛； 这不承诺 arbitrary custom vocabulary 的执行语义。OpenAPI 3.2.x 契约见 OpenAPI 3.2 支持矩阵，不会把 3.2 当作 3.1 处理。
OpenAPI 3.2 消费（已发布）
Java 5.7.0 与 Knife4x Go v0.8.0 接入 OpenAPI 3.2.x 完整消费。真实 springdoc 生成仍停留在 3.0/3.1。
| 范围 | 状态 | 契约 |
|---|---|---|
| 规范 3.2 夹具消费 | ✅ | React / WebJar / starter 合成入口 / Disk 聚合 / Knife4x SpecURL |
| 真实 springdoc 3.2 生成 | 未做 | 当前源码 POM 为 1.8.0 / 2.9.1 / 3.0.3，只证明 3.0/3.1 生成 |
| 用户矩阵与限制 | ✅ | OpenAPI 3.2 支持矩阵 |
React / Vue3 相对 Vue2 的功能缺口
能力基线是 upstream Vue2（本仓库 legacy/vue2），不是本仓库的 Vue3 重写。front/vue3（OAS2 兼容维护）与 front/ui-react（OAS3 主线）都是维护者重写，各自可能漏掉 Vue2 能力。⬜ = 未实现，🔲 = 部分实现，✅ = 已实现。
Vue3 相对 Vue2 已确认并修复的回归：聚合路由头曾误写为 knfie4j-gateway-request（现已改回 knife4j-gateway-request）；侧边栏搜索曾失去 Tag 名称命中后展开全部子接口的行为（现已对齐 Vue2）。
核心功能
| 功能 | Vue2 基线 | Vue3 | React | 缺口说明 |
|---|---|---|---|---|
| 接口文档展示 | ✅ | ✅ | ✅ | — |
| 接口调试 | ✅ | ✅ | ✅ | — |
| 数据模型展示 | ✅ | ✅ | ✅ | — |
| 分组切换 | ✅ | ✅ | ✅ | — |
| 接口搜索 | ✅ 当前分组；Tag 名称命中则展开全部子接口 | ✅ 已对齐 Vue2 | ✅ 当前分组 | 跨分组搜索不是 Vue2 能力 |
| Authorize 鉴权 | ✅ | ✅ | ✅ | React 支持 securitySchemes 动态渲染 + OAuth2 四种 flow 基础 token 获取/注入 |
| 全局参数 | ✅ | ✅ | ✅ | — |
| 离线文档导出 | ✅ | ✅ | 🔲 | React 支持 HTML/Word/Markdown/OpenAPI JSON / YAML，缺少 Word 模板自定义 |
| 首页统计 | ✅ | ✅ | ✅ | — |
调试页详细缺口
| 功能 | Vue2 基线 | Vue3 | React | 缺口说明 |
|---|---|---|---|---|
| multipart/form-data 文件上传 | ✅ | ✅ | 🔲 | 基础表单可用，完整文件上传待优化 |
| OAuth2 password/client_credentials | ✅ | ✅ | ✅ | 基础 tokenUrl 换取 token 已实现 |
| afterScript（请求后脚本） | ✅ | ✅ | ⬜ | Vue2 / Vue3 有，React 暂无 |
| 调试后刷新变量 | ✅ | ✅ | ⬜ | 对应 enable-reload-cache-parameter |
增强功能
| 功能 | Vue2 基线 | Vue3 | React | 缺口说明 |
|---|---|---|---|---|
@ApiSupport.order Tag 排序 | ✅ | ✅ | ✅ | React 按 spec 中的 x-order 排序，缺失时保持原有排序策略 |
@ApiSupport.author/authors 展示 | ✅ | ✅ | ✅ | 类级作者由后端回退写入 operation x-author，React 在接口详情页展示，不做 Tag 级聚合 |
@ApiOperationSupport.order 操作排序 | ✅ | ✅ | ✅ | React 按 spec 中的 x-order 排序，缺失时保持原有排序策略 |
@ApiOperationSupport.author/authors 展示 | ✅ | ✅ | ✅ | 后端合并为 operation x-author，React 展示非空作者字符串 |
| 自定义 Markdown 文档 | ✅ | ✅ | ✅ | React 读取 x-openapi.x-markdownFiles 并在侧边栏渲染 |
| 自定义 Footer | ✅ | ✅ | ✅ | React 读取 enableFooterCustom / footerCustomContent 并按 Markdown 安全渲染 |
| 接口变化提示 | ✅ 侧边栏小蓝点 | ✅ 同 Vue2 | ✅ NEW / 变化标记 | React 已实现，UX 不同于 Vue2 |
| 请求参数缓存 | ✅ | ✅ | ✅ | React 已读取 enable-request-cache |
| TypeScript 代码生成 | ✅ | ✅ | ✅ | React 操作页提供基础 JS / TypeScript 请求函数片段 |
| OpenAPI 复制/下载 | ✅ 接口页 JSON | ✅ 同 Vue2 | ✅ JSON / YAML / 单接口闭包 | 三端都没有独立的 Postman Collection 导出器 |
knife4j-core 已抽取模块
| 模块 | 状态 | 说明 |
|---|---|---|
resolveRef(ref, doc) | ✅ | 统一 OAS2/OAS3 $ref 解析 |
OperationDebugModel | ✅ | 从 operation 解析参数模型 |
requestBuilder | ✅ | 统一请求构造 + curl 输出 |
buildSchemaExample | ✅ | schema 示例生成 |
buildSchemaFieldTree | ✅ | schema 字段树 |
requestBuilder Cookie 合并 | ✅ | 按 RFC 7230 大小写不敏感合并 Cookie 头，避免 cURL 输出重复键 |
优先级排序原则
- 稳定性优先：Bug 修复和兼容性回归永远优先于新功能
- 调试能力对齐：Vue2 基线能做的调试流程，React 也必须能做；Vue3 只作为 OAS2 兼容端口，不能单独充当能力基线
- 核心层先行：knife4j-core 抽取完成后，UI 层改动才可控
- 小步快跑：一个 PR 只做一件事，可独立验证和回滚
- 不破坏现有体验：任何改动不能让
doc.html用户降级
暂时不要做的事
- 不要同时重构后端、前端、文档和品牌
- 不要假设所有历史文档都要立刻迁完
- 不要把实验性的 UI 线写成当前默认实现
- 不要为了代码优雅牺牲向后兼容
- 不要一次性停掉 OAS2 兼容维护（
front/vue3仍然可用）
下一步
- 继续补齐
knife4j.setting.*UI 开关联动：React 前端已读取部分x-openapi.x-setting字段；仍缺 afterScript 与调试后刷新变量 - 补齐 multipart/form-data 文件上传细节
如果你想参与某个任务的实现，欢迎提 Issue 或 PR。详见 GitHub 仓库。