Knife4j 接口文档按微服务多分组(#1404)

日期: 2026-04-25 关联 PR: #1405(Phase A) / #1406-#1410(Phase B 5 服务) / #1411(hotfix) 工单: #1404

🚨 前端 / 测试同事必看

接口文档地址不变

测试环境:https://api.test.1814.love:9443/doc.html(网关)
内网直连:http://192.168.100.236:8080/doc.html

左上角下拉菜单变化

改造前:35 个细粒度下拉项,如:

用户服务 - 管理员管理
用户服务 - 角色管理
用户服务 - 字典管理
资源服务 - 酒店管理
资源服务 - 服务项管理
... (35 项,菜单冗长)

改造后:5 个微服务级下拉:

用户服务
资源服务
产品服务
订单服务
小程序 BFF

进入 group 后的 tag 列表

每个 tag 用 4 类前缀区分端类型,无需服务名前缀:

[admin] 模块名 - 管理端接口
[C端] 模块名 - 小程序端接口
[内部] 模块名 - internal/Feign 接口
[回调] 模块名 - 第三方平台事件回调(企微/公众号)

实例

用户服务 group(共 48 tag):

[C端] 公开字典 / [C端] 出行人 / [C端] 出行人OCR识别 / ...
[admin] Banner管理 / [admin] 角色管理 / [admin] 字典管理 / ...
[内部] 心愿 / [内部] 联系我们 / [内部] 部门用户 / ...
[回调] 公众号回调

订单服务 group(共 51 tag):

[admin] 订单管理 / [admin] 合同管理 / [admin] 退款管理 / [admin] 保险方案管理 / ...
[内部] 订单同步 / [内部] 支付 / [内部] 合同 Feign / ...

改造规模(供 reviewer 参考)

7 PR(#1405-#1411)
274 Controller 文件 @Api(tags) 全量改名
5 个 Knife4jConfig.java 多 Docket 合并为单 Docket
gateway/application.yml knife4j.gateway.routes 35 项 → 5 项

路由结构

服务	网关下拉名	swagger group	注册名
hl-user-service	用户服务	用户服务	hl-user-service
hl-resource-service	资源服务	资源服务	hl-resource-service
hl-product-service-v2	产品服务	产品服务	hl-product-service-v2
hl-order-service-v2	订单服务	订单服务	hl-order-service(注:代码模块带 -v2 但 Nacos 注册名不带)
hl-mp-service	小程序 BFF	小程序 BFF	hl-mp-service

实施踩坑

PR #1405 把订单服务 service-name 误写为 hl-order-service-v2(实际 Nacos 注册名是 hl-order-service,代码模块名带 -v2 是 maven module 名,但 spring.application.name 没带 -v2),导致 doc.html 订单 group 404。已在 #1411 hotfix 修正。

经验沉淀:Knife4j gateway routes / Feign client name 统一参考 Nacos 注册名(spring.application.name)而非 maven module 名,二者可能不一致。

不影响业务接口

本次仅改文档/分组,业务路径 / 鉴权 / 错误码 / Feign 调用全部不变。

2.9 KiB 原始文件 Blame 文件历史