Swagger如何根据标签为不同分组的同接口设置对应默认示例

原生OpenAPI 2.0/3.x 规范没有提供「同一操作绑定多标签时，按标签维度单独配置默认示例」的原生能力，不需要重复写3份接口定义，下面两个方案都可以实现需求，后续改接口只需要维护单份定义：

方案1：Swagger UI 前端钩子动态适配（最推荐，无规范冗余） #

Swagger UI初始化时暴露了完整的生命周期钩子，不需要改后端的OpenAPI结构，加一段简单的JS逻辑就能实现，完全复用你已经写好的三个components/examples引用。

• 实现逻辑：
  • 监听标签切换、接口面板展开事件
  • 判断当前接口面板所属的激活标签，自动匹配对应枚举值选中对应示例
  • 同步给路径参数type赋值，保证参数和示例一致
• 直接把下面的配置追加到你现有的Swagger UI初始化代码里即可：

const ui = SwaggerUIBundle({
  // 保留你原来的url、dom_id、presets等所有原有配置
  onComplete: () => {
    const tagDefaultMap = {
      Fly: "bird",
      Swim: "fish",
      Run: "mammal"
    };
    // 统一监听点击事件，覆盖标签切换、接口展开操作
    document.addEventListener("click", () => {
      setTimeout(() => {
        // 取当前展开的标签名
        const activeTagEl = document.querySelector(".opblock-tag-section.is-open .opblock-tag");
        if (!activeTagEl) return;
        const activeTag = activeTagEl.textContent.trim().split("\n")[0];
        // 定位当前标签下展开的目标接口
        const targetApi = document.querySelector('.opblock-tag-section.is-open .opblock[data-path="/animal/{type}"]');
        if (!targetApi || !tagDefaultMap[activeTag]) return;
        // 自动切对应示例
        const exampleSelect = targetApi.querySelector('select[data-testid="example-select"]');
        const targetVal = tagDefaultMap[activeTag];
        if (exampleSelect && exampleSelect.value !== targetVal) {
          exampleSelect.value = targetVal;
          exampleSelect.dispatchEvent(new Event("change"));
        }
        // 同步设置路径参数值
        const typeInput = targetApi.querySelector('input[data-param-name="type"]');
        if (typeInput) typeInput.value = targetVal;
      }, 50);
    });
  }
});

如果你的接口不是GET方法，只需要对应调整接口DOM的选择器即可，不同小版本Swagger UI的DOM类名如果有细微差异，按浏览器开发者工具里实际的结构改下选择器就行，逻辑通用。

方案2：规范层加discriminator映射（零前端代码，全工具兼容） #

如果你不方便改Swagger UI的前端初始化代码，可以在现有单份接口定义里给type参数加鉴别器映射，不需要拆分接口，所有兼容OpenAPI规范的工具都能识别：

paths:
  /animal/{type}:
    get:
      tags: [Fly, Swim, Run]
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [bird, fish, mammal]
            discriminator:
              propertyName: type
              mapping:
                bird: '#/components/examples/bird'
                fish: '#/components/examples/fish'
                mammal: '#/components/examples/mammal'
          examples:
            bird:
              $ref: '#/components/examples/bird'
            fish:
              $ref: '#/components/examples/fish'
            mammal:
              $ref: '#/components/examples/mammal'
      # 其余响应、参数配置和原有逻辑完全一致

这个方案不需要改前端代码，Swagger UI加载时会自动根据discriminator的映射匹配当前上下文选中对应默认值。

你之前考虑的调整示例排列顺序的方案虽然能跑，但维护性极差，一旦后续调整标签顺序、新增标签，默认匹配关系就会错乱，不建议生产环境用。

内容的提问来源于stack exchange，提问作者Bob Ramsey