How can I override example in openapi spec? - swagger

Question

I've got the following spec:
---
openapi: 3.0.0
info:
title: Players API
version: 0.0.1-alpha1
paths:
/players/{id}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PlayerWrapper'
components:
schemas:
PlayerWrapper:
type: object
properties:
display_name:
type: string
example: 76ers
config:
description: |
The configuration of the player.
example: { spec: { team: 76ers, names: [ 1, 2 ] } }
allOf:
- $ref: '#/components/schemas/Player'
Player:
type: object
properties:
spec:
allOf:
- $ref: '#/components/schemas/BasicPlayer'
additionalProperties: false
BasicPlayer:
type: object
properties:
team:
type: string
names:
allOf:
- $ref: '#/components/schemas/Names'
additionalProperties: false
Names:
type: array
items:
type: string
example: [ Ben, Joel ]
I did verify on Swagger that it's indeed valid. The question is why I can see names: [ 1, 2 ] other than [ Ben, Joel ]. When I do remove that example thing (# example: { spec: { team: 76ers, names: [ 1, 2 ] } }), I can see Ben, Joel example:
Is there a way how I can force override / merge those example? As of now, I feel like my example gets overriden by either of those fields (i.e., either 76ers / [1, 2] or string / [Ben, Joel] but I'd like to get 76ers / [Ben, Joel] instead).

Answer 1

The structure in your schemas isn't quite right. The idea is to provide examples on the simple types (strings, int, etc) and the schema will structure it as required.
So dont put the example on config, put it on the nested simple types like this, ie BasicPlayer object should have the example on team as it's a string:
BasicPlayer:
type: object
properties:
team:
type: string
example: '76ers'
names:
allOf:
- $ref: '#/components/schemas/Names'
Similar with PlayerWrapper.config don't try and give a full object in the example, it gets composed by the member properties. So team gets an example, but Names example is composed from the child type.
PlayerWrapper:
type: object
properties:
display_name:
type: string
example: '76ers'
config:
description: |
The configuration of the player.
allOf:
- $ref: '#/components/schemas/Player'
Which should give you the expected example:
Here's the full swagger:
---
openapi: 3.0.0
info:
title: Players API
version: 0.0.1-alpha1
paths:
/players/{id}:
get:
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PlayerWrapper'
components:
parameters:
id:
name: id
in: path
required: true
schema:
type: string
description: The id.
schemas:
PlayerWrapper:
type: object
properties:
display_name:
type: string
example: '76ers'
config:
description: |
The configuration of the player.
allOf:
- $ref: '#/components/schemas/Player'
Player:
type: object
properties:
spec:
allOf:
- $ref: '#/components/schemas/BasicPlayer'
additionalProperties: false
BasicPlayer:
type: object
properties:
team:
type: string
example: '76ers'
names:
allOf:
- $ref: '#/components/schemas/Names'
additionalProperties: false
Names:
type: array
items:
type: string
example:
- Ben
- Joel
Note it is possible to override schema examples with an example in the resource definition like this:
paths:
/players/{id}:
get:
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PlayerWrapper'
example:
display_name: 76ers
config:
spec:
team: 76ers
names:
- 'Ben'
- 'Joel'