CODEWITHSUNDEEP
swaggeropenapi
Robdll
Robdll

Reputation: 6255

how to place multiple items in example array using refs - Open API

I'm writing an API doc, and I have an endpoint returning multiple items of the same thing. I would like to have more items in the response example, but coming from different refs

here is the endpoint response documentation:

      responses:
        '200':
          description: json containing the updated notification
          content:
            application/json:
              schema:
                type: object
                properties:
                  payload:
                    type: array
                    items:
                      $ref: "#/components/schemas/forecast_item"

here's the item schema:

    forecast_item:
      type: object
      properties:
        transmission_date:
          type: string
        timestamp:
          type: number
        temperature:
          type: number
        humidity:
          type: number
        rain:
          type: number
        icon:
          type: string
      example:
        transmission_date: "2022-06-08 12:00:00"
        timestamp: 1654689600
        temperature: 28.28
        humidity: 33
        rain: 0
        icon: 04d

the above produce the following example:

{
  "payload": [
    {
      "transmission_date": "2022-06-08 12:00:00",
      "timestamp": 1654689600,
      "temperature": 28.28,
      "humidity": 33,
      "rain": 0,
      "icon": "04d"
    }
  ]
}

I tried the following

                properties:
                  payload:
                    type: array
                    items:
                      $ref: "#/components/schemas/device"
                example:
                  payload: [
                    $ref: "#/components/schemas/device",
                    $ref: "#/components/schemas/device",
                    $ref: "#/components/schemas/device"
                  ]

hoping I would achieve:

{
  "payload": [
    {
      "transmission_date": "2022-06-08 12:00:00",
      "timestamp": 1654689600,
      "temperature": 28.28,
      "humidity": 33,
      "rain": 0,
      "icon": "04d"
    },
{
      "transmission_date": "2022-06-08 12:00:00",
      "timestamp": 1654689600,
      "temperature": 28.28,
      "humidity": 33,
      "rain": 0,
      "icon": "04d"
    },
{
      "transmission_date": "2022-06-08 12:00:00",
      "timestamp": 1654689600,
      "temperature": 28.28,
      "humidity": 33,
      "rain": 0,
      "icon": "04d"
    }
  ]
}

but i did not.

Upvotes: 2

Views: 2581

Answers (1)

Helen
Helen

Reputation: 97540

To add a multi-item example for an array, place the example on the same level as type: array. The example value should be the full sample array, in the YAML or JSON format. $ref is not supported within the example value.

                properties:
                  payload:
                    type: array
                    items:
                      $ref: "#/components/schemas/device"

                    example:
                      - transmission_date: '2022-06-08 12:00:00'
                        timestamp: 1654689600
                        temperature: 28.28
                        humidity: 33
                        rain: 0
                        icon: 04d
                      - transmission_date: '2022-06-08 12:00:00'
                        timestamp: 1654689600
                        temperature: 28.28
                        humidity: 33
                        rain: 0
                        icon: 04d
                      - transmission_date: '2022-06-08 12:00:00'
                        timestamp: 1654689600
                        temperature: 28.28
                        humidity: 33
                        rain: 0
                        icon: 04d

Upvotes: 2

Related Questions