Swagger UI与OpenAPI 3：$ref引用示例切换请求体失效问题咨询

我有两个带示例的Schema，想通过下拉框切换请求体。用"value"定义示例时，请求体可以正常切换；但用$ref引用Schema作为示例时，只有第一个示例能加载，切换下拉框无法显示第二个示例。这是功能未实现、Bug还是我的配置有误？

我的配置示例如下：

"requestBody": {
  "content": {
    "application/json": {
      "schema": {
        "oneOf": [
          {"$ref": "#/components/schemas/reportexample1"},
          {"$ref": "#/components/schemas/reportexample2"}
        ]
      },
      "examples": {
        "reportexample1": {
          "summary": "reportexample1",
          "$ref": "#/components/schemas/reportexample1"
        },
        "reportexample2": {
          "summary": "reportexample2",
          "$ref": "#/components/schemas/reportexample2"
        }
      }
    }
  }
},

"components": {
  "schemas": {
    "reportexample1": {
      "type": "object",
      "properties": { .... }
    },
    "reportexample2": {
      "type": "object",
      "properties": { .... }
    }
  }
}

这不是你的配置错误，而是OpenAPI规范中examples字段的$ref引用逻辑限制，同时部分OpenAPI工具（比如Swagger UI）对这种引用的支持存在兼容性问题：

• OpenAPI 3.x规范里，examples下的每个示例对象应该用value字段提供具体示例值，而不是直接引用Schema。Schema的$ref是用来定义数据结构的，不是用来填充示例内容的——你当前用$ref指向Schema，本质上是把结构定义当成了示例值，这不符合规范的设计意图。
• 部分工具（比如Swagger UI）会对第一个$ref做兼容解析，但后续的引用不会触发重新渲染，这就导致切换下拉框后第二个示例无法加载。

正确的配置方式 #

不要直接在examples里引用Schema，而是给每个示例单独指定value（可以基于Schema的结构生成示例值），或者用externalValue指向外部示例文件：

"requestBody": {
  "content": {
    "application/json": {
      "schema": {
        "oneOf": [
          {"$ref": "#/components/schemas/reportexample1"},
          {"$ref": "#/components/schemas/reportexample2"}
        ]
      },
      "examples": {
        "reportexample1": {
          "summary": "reportexample1",
          "value": {
            // 填写符合reportexample1结构的具体示例值
            "prop1": "示例值1"
          }
        },
        "reportexample2": {
          "summary": "reportexample2",
          "value": {
            // 填写符合reportexample2结构的具体示例值
            "propA": "示例值A",
            "propB": 123
          }
        }
      }
    }
  }
}

如果想复用示例内容，可以把示例定义在components/examples里，再通过$ref引用这些示例对象，而不是引用Schema：

"requestBody": {
  "content": {
    "application/json": {
      "schema": {
        "oneOf": [
          {"$ref": "#/components/schemas/reportexample1"},
          {"$ref": "#/components/schemas/reportexample2"}
        ]
      },
      "examples": {
        "reportexample1": {
          "$ref": "#/components/examples/reportexample1"
        },
        "reportexample2": {
          "$ref": "#/components/examples/reportexample2"
        }
      }
    }
  }
},
"components": {
  "schemas": {
    "reportexample1": {
      "type": "object",
      "properties": { .... }
    },
    "reportexample2": {
      "type": "object",
      "properties": { .... }
    }
  },
  "examples": {
    "reportexample1": {
      "summary": "reportexample1",
      "value": {
        "prop1": "示例值1"
      }
    },
    "reportexample2": {
      "summary": "reportexample2",
      "value": {
        "propA": "示例值A"
      }
    }
  }
}

这样配置后，下拉框切换示例就能正常显示内容了。

内容的提问来源于Stack Exchange，提问作者JDev