时间戳

首页 > 解决方案 > 多响应正文示例取决于 OpenApi 3.0.0/Swagger 中的媒体类型

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

问题描述

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

标签： apiswaggerdocumentationopenapi

解决方案

$refOpenAPI 3.0 中的示例有两种方式：

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

笔记：

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

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

推荐阅读