Swagger 不支持为同一个 API 接口在不同标签下显示不同的 notes 或描述内容；其 @ApiOperation 的 notes、value 等字段是接口级而非标签级的，因此无法实现“同一路径、不同标签、不同说明”的动态描述。唯一可行的替代方案是通过语义化路径区分。
swagger 不支持为同一个 api 接口在不同标签下显示不同的 `notes` 或描述内容；其 `@apioperation` 的 `notes`、`value` 等字段是接口级而非标签级的，因此无法实现“同一路径、不同标签、不同说明”的动态描述。唯一可行的替代方案是通过语义化路径区分。
在实际微服务或模块化 API 设计中，开发者常希望通过 tags = {"tag1", "tag2"} 将一个通用接口（如 /readplans）同时归类到多个业务域（如“计费模块”和“产品配置模块”），并期望在 Swagger UI 中，当该接口出现在 tag1 下时显示“读取计费套餐”，而在 tag2 下时显示“查询产品扩展计划”。遗憾的是，Swagger 2.x（Springfox）及 OpenAPI 3.x（Springdoc）均不支持基于 tag 的条件化描述渲染——@ApiOperation.notes 或 @Operation(description = "...") 是绑定到具体 @RequestMapping 方法的，与它被分配到哪些 tag 无关。
✅ 正确实践：使用语义化路径 + 独立接口声明
虽然逻辑复用，但需为每个 tag 显式定义独立端点，并分别配置专属描述：
// 归属 tag1：面向计费场景的描述
@Operation(summary = "读取计费套餐列表",
description = "返回当前租户可用的计费周期与价格方案，用于账单生成。",
tags = {"tag1"})
@GetMapping(value = "/readplans-for-billing", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<String[]> readPlansForBilling() {
return buildPlansResponse();
}
// 归属 tag2：面向产品配置的描述
@Operation(summary = "查询产品扩展计划",
description = "获取可绑定至基础产品的增值计划列表，支持前端动态组装配置页。",
tags = {"tag2"})
@GetMapping(value = "/readplans-for-product", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<String[]> readPlansForProduct() {
return buildPlansResponse();
}
// 共享核心逻辑（避免重复）
private ResponseEntity<String[]> buildPlansResponse() {
String[] plans = {"plana", "planb", "planc"};
return ResponseEntity.ok(plans);
}⚠️ 注意事项：
- 不要试图通过 @Api(tags = {...}) 类级别注解或自定义 OperationCustomizer 实现运行时描述覆盖——这些方式无法改变已注册的 Operation 对象的 description 字段在不同 tag 上的渲染行为；
- 若强制复用同一路径（如 /readplans）并硬编码双 tag，Swagger UI 仅会显示一份文档（以首次注册或最终解析结果为准），不会为每个 tag 渲染独立描述块；
- 在 OpenAPI 3.x（Springdoc）中，可通过 @RouterOperation 或 OpenApiCustomiser 深度定制文档结构，但仍无法让单个 @Operation 在多个 tag 下呈现不同 description，本质仍是「一个 Operation → 一个 path item」的映射关系。
? 总结：
Swagger 的设计哲学是「接口即契约」，每个 HTTP 路径对应唯一、明确的语义描述。所谓“按 tag 切换描述”，实则混淆了分类维度（tag） 与 语义维度（endpoint）。真正健壮的 API 文档应通过清晰的路径命名（/v1/billing/plans vs /v1/product/addons）和精准的 @Operation 注解来表达意图，而非依赖 tag 的上下文感知能力——后者本就未被规范支持。坚持路径语义化 + 接口职责单一，才是可持续维护高质量 Swagger 文档的根本路径。
