模块说明

仓库顶层目录

目录	说明
knife4j/	Java 主工程——用户实际引入的 starter 和 webjar 都在这里构建
front/	活跃前端：core + ui-react（OAS3）、vue3（OAS2 兼容）
knife4x/	Go/Rust 嵌入式控制台骨架（规划中，UI 共用 front/ui-react）
docs/	当前 VitePress 文档站
tools/	验证、发布与任务看板脚本
legacy/	冻结参考（vue2、insight、sandbox），不参与主线构建

Java 模块（knife4j/ 下）

核心

模块	说明	用户是否直接引入
knife4j-core	核心逻辑：过滤器、配置解析、vendor extension、OpenAPI 自定义器等	间接（starter 传递）
knife4j-dependencies	BOM（dependencyManagement），统一管理所有版本	间接（父 POM 继承）

UI（Webjar）

模块	说明	前端技术
knife4j-openapi2-ui	Swagger 2 专用 UI webjar，doc.html 入口；打包本仓库 front/vue3 的 vite 构建产物	Vue 3
knife4j-openapi3-ui	OpenAPI 3 专用 UI webjar，doc.html 入口；打包 front/ui-react 的 vite 构建产物	React

Starter（WebMvc）

模块	适用 Boot 版本	依赖的 springdoc	依赖的 UI
knife4j-openapi2-spring-boot-starter	2.x	—（用 Springfox）	knife4j-openapi2-ui（Vue 3）
knife4j-openapi3-spring-boot-starter	2.x	springdoc-openapi-ui 1.8.0	knife4j-openapi3-ui（React）
knife4j-openapi3-jakarta-spring-boot-starter	3.x	springdoc-openapi-starter-webmvc-ui 2.8.9	knife4j-openapi3-ui（React）
knife4j-openapi3-boot4-spring-boot-starter	4.x	springdoc-openapi-starter-webmvc-ui 3.0.3	knife4j-openapi3-ui（React）

Starter（WebFlux）

模块	适用 Boot 版本	说明
knife4j-openapi3-webflux-spring-boot-starter	2.x	纯依赖编排，无后端增强
knife4j-openapi3-webflux-jakarta-spring-boot-starter	3.x	纯依赖编排，无后端增强

Starter（Gateway & 聚合）

模块	适用 Boot 版本	场景
knife4j-gateway-spring-boot-starter	3.x	Spring Cloud Gateway WebFlux 聚合
knife4j-gateway-webmvc-spring-boot-starter	3.5	Spring Cloud Gateway Server Web MVC 聚合；DISCOVER 读取已配置的 lb:// 路由
knife4j-gateway-boot4-spring-boot-starter	4.x	Spring Cloud Gateway 5 WebFlux 聚合
knife4j-aggregation-spring-boot-starter	2.x	独立聚合（Disk/Cloud/Nacos/Eureka/Polaris）
knife4j-aggregation-jakarta-spring-boot-starter	3.x	独立聚合（Jakarta 版）
knife4j-aggregation-boot4-spring-boot-starter	4.x	独立聚合（springdoc-openapi 3.x）

其他

模块	说明
knife4j-demo-openapi3	OpenAPI 3 在线演示应用（Boot 4.0.6 + Boot4 starter + React UI，部署到 openapi3.demo.knife4jnext.com）
knife4j-demo-openapi2	OpenAPI 2 在线演示应用（Boot 2.7.18 + springfox 2.10.5 + Vue 3 UI，部署到 openapi2.demo.knife4jnext.com）
knife4j-smoke-tests	自动化冒烟测试（14 个子模块覆盖 Boot 2.x OAS2/OAS3/WebFlux/独立聚合、Boot 3.x Jakarta/WebFlux/Gateway WebFlux/Gateway Server Web MVC/独立聚合、Boot 4.x WebMVC/Gateway/独立聚合）

选型决策树

你的项目是什么？
│
├── 普通 Spring Boot WebMvc 应用
│   ├── Boot 2.x + 要用 Swagger 2 / Springfox
│   │   └── knife4j-openapi2-spring-boot-starter
│   ├── Boot 2.x + 要用 OpenAPI 3
│   │   └── knife4j-openapi3-spring-boot-starter
│   ├── Boot 3.x
│   │   └── knife4j-openapi3-jakarta-spring-boot-starter
│   └── Boot 4.x
│       └── knife4j-openapi3-boot4-spring-boot-starter
│
├── Spring Boot WebFlux 应用（非网关）
│   ├── Boot 2.x
│   │   └── knife4j-openapi3-webflux-spring-boot-starter
│   └── Boot 3.x
│       └── knife4j-openapi3-webflux-jakarta-spring-boot-starter
│
├── Spring Cloud Gateway 网关
│   ├── Boot 3.x WebFlux → knife4j-gateway-spring-boot-starter
│   ├── Boot 3.5 Server Web MVC → knife4j-gateway-webmvc-spring-boot-starter
│   └── Boot 4.x WebFlux → knife4j-gateway-boot4-spring-boot-starter
│
└── 非网关的微服务聚合
    ├── Boot 2.x
    │   └── knife4j-aggregation-spring-boot-starter
    ├── Boot 3.x
    │   └── knife4j-aggregation-jakarta-spring-boot-starter
    └── Boot 4.x
        └── knife4j-aggregation-boot4-spring-boot-starter

前端工作区（front/ 下）

目录	package name	说明
ui-react/	knife4j-ui-react	React 新前端，已集成进 knife4j-openapi3-ui webjar
core/	knife4j-core	前端 OpenAPI 解析核心库
vue3/	knife4j-vue3	OAS2 兼容 UI（独立 bun 工程），打包进 knife4j-openapi2-ui

注意事项

• 不要同时引入多个 starter。WebMvc / WebFlux / Gateway / Aggregation 是互斥的，选一个即可。
• openapi2 starter 不兼容 Boot 3.x。它依赖 Springfox，Springfox 不支持 Jakarta。
• Boot 4.x 使用专用 starter。不要把 Boot 3.x Jakarta starter 直接带到 Boot 4.x。
• WebFlux starter 不含后端增强。@ApiOperationSupport、knife4j.setting.* 等能力仅 WebMvc starter 提供。详见 WebFlux 接入。