多个响应正文示例，具体取决于 OpenApi 3.0.0/Swagger 中的媒体类型

Question

>我正在尝试记录一个端点的响应，该端点接受多个 mime 类型请求并根据类型返回不同的响应。一种响应类型 pdf 返回自己的架构，与其他响应类型分开。其余的都返回相同的架构和相同的示例。此语法有效。几乎。除了在 UI 示例中，JSON 响应还显示字符串"$ref：example-two.json"以及相应的响应示例。喜欢：

{
"key": "value",
"key2": "value2",
"$$ref: example-two.json"
}

当它应该只是：

{
"key": "value",
"key2": "value2"
}

我一直在搜索文档、堆栈和谷歌，我没有看到任何制作这样的东西的例子。或者更确切地说，我不明白为什么这个不起作用，但我还没有看到任何包含每个示例$refs的示例。

responses:
200:
content:
application/pdf:
schema:
$ref: ../app.yaml#/components/schemas/ModelOne
application/json:
schema:
$ref: ../app.yaml#/components/schemas/ModelTwo
examples:
Example:
value:
$ref: example-two.json
text/html:
schema:
$ref: ../app.yaml#/components/schemas/ModelTwo
examples:
Example:
value:
$ref: example-two.json

对于上下文 - 我无法更改端点行为，我确实需要为每个 mime 类型显示一个示例，即使它们相同。因为那个不一样。提前谢谢你！

Answer 1

有两种方法可以在OpenAPI 3.0中$ref示例：

1( 在components/examples部分中定义示例。在这种情况下，$ref在examples.<name>键内使用(而不是在value内(。

examples:
Example:
$ref: '#/components/examples/MyExample'
...
components:
examples:
MyExample:
summary: Optional short description of this example
value:
key: value
key2: value2

2( 如果example-two.json文件仅包含示例值(在本例中为 - 示例 JSON(，则可以使用externalValue链接到该文件：

examples:
Example:
externalValue: example-two.json

笔记：

• externalValue中的相对URL是根据API服务器URL(servers[*].url(而不是OpenAPI定义文件的位置解析的。您可能需要使用绝对网址。

• 带有externalValue的示例目前(截至 2019 年 12 月(未显示在 Swagger UI 中 - 请参阅问题 #5433。