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

Question

我正在尝试使用 OpenAPI 3、YAML 来构建 API 定义。我一直在使用文档https://swagger.io/docs/specation/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。

我可以在 中定义一个 JSON 正文数组吗components | examples？还是不可能？

如果可能的话，我需要改变什么才能让它工作？

Answer 1

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

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'