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

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.

Answer 1

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