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

Posted 2023-03-15

【中文标题】多响应正文示例取决于 OpenApi 3.0.0/Swagger 中的媒体类型

【英文标题】：Multiple Response Body Examples depending on media type in OpenApi 3.0.0/Swagger

【发布时间】：2020-03-26 16:14:00

【问题描述】：

我正在尝试记录接受多个 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 类型展示一个示例，即使它们是相同的。因为一个不同。先感谢您！

【参考方案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。

【讨论】：

感谢您的回复！当我在没有值的情况下尝试它时：在您的第一个示例示例之后的键，不幸的是，什么都没有显示。我无法使用第二个示例，因为我需要它在 UI 中显示。

您使用什么版本的 Swagger UI？打开浏览器开发工具 > 控制台选项卡并评估 versions。

您是按原样使用我的第一个示例，还是尝试$ref 那里的外部文件？如果是后者，外部文件的内容是什么？

是的，我不得不尝试 $ref，$ref 是具有预期 json 输出的本地 json 文件。我在 Swagger UI "version":"3.23.6"

"$ref 是一个本地 json 文件，具有预期的 json 输出。" 这就是问题所在。外部 JSON 文件的格式必须为 OAS3 Example Object，即"summary": "Optional short description of this example", "value": "key": "value", "key2": "value2"。