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

Question

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.

Helen · Accepted Answer · 2022-06-15 06:02:38Z

2

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

answered Jun 15, 2022 at 6:02

Helen

99.8k17 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

Robdll Over a year ago

ok so I actually have to write 3 times the item, correct ?

Helen Over a year ago

Yes, the example can contain as many items as you want.

Collectives™ on Stack Overflow

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

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related