多响应正文示例取决于 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 定义文件的位置进行解析。您可能需要使用绝对 URL。

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