How to reference array item examples in OpenAPI 3? - swagger-ui

Question

Using this schema definition:
schemas:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel1'
example:
- id: 1
firstName: Sherlock
lastName: Holmes
- id: 2
firstName: John
lastName: Watson
I get this expected result:
[
{
"id": 1,
"firstName": "Sherlock",
"lastName": "Holmes"
},
{
"id": 2,
"firstName": "John",
"lastName": "Watson"
}
]
Now I'd like to reuse the Holmes example for both the single user (ContactModel1) and as part of an array of users (AllContacts). But if I use the referenced examples:
schemas:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel1'
example:
Homes:
$ref: '#/components/examples/Homes'
Watson:
$ref: '#/components/examples/Watson'
examples:
Holmes:
value:
id: 1
first_name: Sherlock
last_name: Holmes
Watson:
value:
id: 2
first_name: John
last_name: Watson
I get this unexpected result in Swagger UI:
[
{
"value": {
"id": 1,
"first_name": "Sherlock",
"last_name": "Holmes",
},
"$$ref": "#/components/examples/Holmes"
},
{
"value": {
"id": 2,
"first_name": "John",
"last_name": "Watson",
},
"$$ref": "#/components/examples/Watson"
}
]
and a similar unexpected example for GET /user/1:
[
{
"value": {
"id": 1,
"first_name": "Sherlock",
"last_name": "Holmes",
},
"$$ref": "#/components/examples/Holmes"
}
]
What am I doing wrong?
I am using this doc as reference:
https://swagger.io/docs/specification/adding-examples/#reuse

Answer 1

This is NOT a valid definition:
components:
schemas:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel1'
example:
Homes:
$ref: '#/components/examples/Homes'
Watson:
$ref: '#/components/examples/Watson'
1) The example syntax is wrong. OpenAPI 3.0 has two keywords for examples - example (singular) and examples (plural). They work differently:
example requires an inline example and does not support $ref.
examples is a map (collection) of named examples. It supports $ref - but you can only $ref whole examples, not individual parts of an example. This also means it's not possible to build an example from multiple $refs. Note that not all elements support plural examples.
Note for Swagger UI users: Swagger UI currently supports example (singular) but not examples (plural). Support for examples is tracked in this issue.
2) The Schema Object only supports singular example but not plural examples. In other words, schemas support inline examples only.
3) In OpenAPI 3.0, schema references use the format #/components/schemas/..., not #/definitions/...
I'd like to use the same EXAMPLE definition for Holmes in both cases, the array of users and the single user.
There's no way to reuse a part of an example in this case. You'll have to repeat the example value in both schemas:
components:
schemas:
ContactModel1:
type: object
properties:
...
example:
id: 1
first_name: Sherlock
last_name: Holmes
AllContacts:
type: array
items:
$ref: '#/components/schemas/ContactModel1'
example:
- id: 1
first_name: Sherlock
last_name: Holmes
- id: 2
first_name: John
last_name: Watson

Answer 2

Use allOf for arrays
components:
schemas:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel1'
example:
allOf:
- $ref: '#/components/examples/Homes'
- $ref: '#/components/examples/Watson'