如何在 OpenAPI 3.0 的组件/示例部分正确定义示例？答案

【问题标题】：How to properly define examples in the components/examples section in OpenAPI 3.0?如何在 OpenAPI 3.0 的组件/示例部分正确定义示例？
【发布时间】：2020-03-04 00:13:46
【问题描述】：

我正在尝试使用 OpenAPI 3、YAML 来构建 API 定义。我一直在使用文档https://swagger.io/docs/specification/adding-examples/ 来了解如何添加示例。

在我的 API 定义中，我有一个返回 JSON 数组的端点。我已经成功地将这个示例作为 API 定义的一部分工作，但现在我试图提取示例并将其移动到 components 部分，但我没有任何运气。

这是我目前拥有的：

paths: 
  /report:
    get:
      parameters: 
        - in: query
          name: dateFrom
          schema:
            type: string
            format: date
          required: true
          example: "2020-01-21"
          description: The start date range
        - in: query
          name: dateTo
          schema:
            type: string
            format: date
          required: true
          example: "2020-02-01"
          description: The end date range
      summary: Used by Anayltics to produce reports showing submission that cannot be determined by GA
      responses:
        '200':
          description: valid response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validresponse'
              example:
                analytics:
                  - date: "2019-01-20"
                    submission: "BaTD"
                    source: "Internal"
                    model: "Model"
                    count: 2
                  - date: "2019-02-20"
                    submission: "BaTD"
                    source: "3rd Party"
                    model: "Model"
                    count: 1  
                  - date: "2019-01-20"
                    submission: "Contact Us"
                    source: "Internal"
                    model: ""
                    count: 20
                  - date: "2019-02-20"
                    submission: "Contact Us"
                    source: "3rd Party"
                    model: ""
                    count: 1

我现在尝试从内联定义中提取示例并将其移至components 部分：

components:
  examples:
    reportResponse:
      analytics:
      - date: "2019-01-20"
        submission: "BaTD"
        source: "Internal"
        model: "Model"
        count: 2
      - date: "2019-02-20"
        submission: "BaTD"
        source: "3rd Party"
        model: "Model"
        count: 1  
      - date: "2019-01-20"
        submission: "Contact Us"
        source: "Internal"
        model: ""
        count: 20
      - date: "2019-02-20"
        submission: "Contact Us"
        source: "3rd Party"
        model: ""
        count: 1

但我在reportResponse 的行上遇到错误：

不应该有额外的属性 additionalProperty: analytics

查看文档，提供的示例提到数组不能是examples 的一部分，而只能是example。

如果我将components 更改为example 而不是examples，那么components 将出现错误。

我可以在components | examples 中定义一个 JSON 正文数组吗，或者这不可能？

如果可能，我需要进行哪些更改才能使其正常工作？

【问题讨论】：

标签： openapi

【解决方案1】：

在示例名称 (reportResponse) 和值 (analytics: ...) 之间添加 value 节点：

components:
  examples:
    reportResponse:
      summary: Short description of this example
      value:   # <--------
        analytics:
        - date: "2019-01-20"
          submission: "BaTD"

现在你可以像这样引用这个例子：

      responses:
        '200':
          description: valid response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validresponse'
              examples:      # <--------
                reportResponse:
                  $ref: '#/components/examples/reportResponse'

【讨论】：