How to properly define examples in the components/examples section in OpenAPI 3.0?

user_1442308 0
Viewed 2185

I am trying to use OpenAPI 3, YAML to build up an API definition. I have been using the docs https://swagger.io/docs/specification/adding-examples/ on how to add examples.

Within my API definition, I have an endpoint that returns a JSON array. I have successfully managed to get this example working as part of the API definition, but now I am trying to extract the example and move it to the components section, but I am not having any luck.

This is that I have currently:

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

I am now trying to extract the example out of the inline definiton and move it to the components section:

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

But I am getting an error on the line with reportResponse:

should NOT have additional properties additionalProperty: analytics

Looking at the documentation, the samples provided mention that an array cannot be part of an examples but only example.

If I change the components to example instead of examples then I am getting an error at the components.

Can I have a JSON body array defined in components | examples, or is this not possible?

If it is possible, what do I need to change to get it working?

openapi
1 Answers

Add the value node betweeen the example name (reportResponse) and value (analytics: ...):

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

Now you can reference this example like this:

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