How to provide an example of an object definition in swagger that contains an array as one of its attributes
11,313
You have to choose between high level examples and low level ones. In Swagger UI, the high level examples precede the local one.
Full example available on Swagger Hub
You can define an example on each property (low level):
Identifier:
type: string
format: uuid
example: Local UUID example
NamedElement:
type: object
properties:
name:
type: string
example: Local identifier example
identifier:
$ref: "#/definitions/Identifier"
required:
- name
- identifier
NamedElementArray:
type: object
properties:
name:
type: string
example: Local name example
elements:
type: array
minLength: 0
items:
$ref: "#/definitions/NamedElement"
required:
- name
- elements
In that case the example will look like this in Swagger UI:
{
"name": "Local name example",
"elements": [
{
"name": "Local identifier example",
"identifier": "Local UUID example"
}
]
}
But you can also give a full example on high level like you did in your example on NamedElement
:
NamedElementArray:
type: object
properties:
name:
type: string
elements:
type: array
minLength: 0
items:
$ref: "#/definitions/NamedElement"
required:
- name
- elements
example:
name: Fred
elements:
- name: Identifier1
identifier: ab804529-11d0-4781-a49a-3bbbc40243df
- name: Identifier2
identifier: zzz4529-11d0-4781-a49a-3bbbc40243df
In that case the example will look like this in Swagger UI:
{
"name": "Fred",
"elements": [
{
"name": "Identifier1",
"identifier": "ab804529-11d0-4781-a49a-3bbbc40243df"
},
{
"name": "Identifier2",
"identifier": "zzz4529-11d0-4781-a49a-3bbbc40243df"
}
]
}
Author by
Geoff
Updated on July 19, 2022Comments
-
Geoff almost 2 years
Referring to the example below, I would like to provide an example of
NamedElementArray
in its definition. This will require showing an example of an array ofNamedElement
for theelements
attribute.How do I do that? I can't find details of how to do this in the swagger specification.
swagger: '2.0' info: version: "0.0.0" title: Example definitions: Identifier: type: string format: uuid NamedElement: type: object properties: name: type: string identifier: $ref: "#/definitions/Identifier" required: - name - identifier example: name: Identifier1 identifier: ab804529-11d0-4781-a49a-3bbbc40243df NamedElementArray: type: object properties: name: type: string elements: type: array minLength: 0 items: $ref: "#/definitions/NamedElement" required: - name - elements example: name: Fred elements: paths: /elements/{name}: get: description: | Gets `NamedElement` objects, based on the **name** query param. parameters: - name: name in: path description: Name of element array to return required: true type: string responses: 200: description: Returns a named element array schema: $ref: "#/definitions/NamedElementArray" default: description: Return nothing