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

Question

我正在尝试使用 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 时遇到错误:

should NOT have additional properties additionalProperty: analytics

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

如果我更改 components至 example而不是 examples然后我在 components 处收到错误消息.

我可以在 components | examples 中定义一个 JSON 主体数组吗？ ，或者这是不可能的？

如果可能，我需要更改什么才能使其正常工作？

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'