SwaggerHub Enterprise
Standardize your APIs with projects, style checks, and
reusable domains.
SwaggerHub Explore
Instantly evaluate the functionality of any API
Swagger Codegen
Generate server stubs and client SDKs from OpenAPI
Specification definitions
Swagger Editor
API editor for designing APIs with the OpenAPI and AsyncAPI specifications.
Swagger UI
Visualize OpenAPI Specification definitions in an
interactive UI.
OAS
3
This guide is for OpenAPI 3.0. If you use OpenAPI 2.0, see our
OpenAPI 2.0 guide
.
Adding Examples
You can add examples to parameters, properties and objects to make OpenAPI specification of your web service clearer. Examples can be read by tools and libraries that process your API in some way. For example, an API mocking tool can use sample values to generate mock requests. You can specify examples for objects, individual properties and operation parameters. To specify an example, you use the
example
or
examples
keys. See below for details.
Note for Swagger UI users:
Support for multiple
examples
is available since Swagger UI 3.23.0 and Swagger Editor 3.6.31.
Note:
Do not confuse example values with default values. An example illustrates what the value is supposed to be. A default value is what the server uses if the client does not provide the value.
Parameter Examples
Here is an example of a parameter value:
parameters:
- in: query
name: status
schema:
type: string
enum: [approved, pending, closed, new]
example: approved # Example of a parameter value
Multiple examples for a parameter:
parameters:
- in: query
name: limit
schema:
type: integer
maximum: 50
examples: # Multiple examples
zero: # Distinct name
value: 0 # Example value
summary: A sample limit value # Optional description
max: # Distinct name
value: 50 # Example value
summary: A sample limit value # Optional description
As you can see, each example has a distinct key name. Also, in the code above, we used an optional
summary
keys with description.
Note:
the sample values you specify should match the parameter data type.
Request and Response Body Examples
Here is an example of the
example
keyword in a request body:
paths:
/users:
post:
summary: Adds a new user
requestBody:
content:
application/json:
schema: # Request body contents
type: object
properties:
type: integer
name:
type: string
example: # Sample object
id: 10
name: Jessica Smith
responses:
'200':
description: OK
Note that in the code above,
example
is a child of
schema
. If
schema
refers to some object defined in the
components
section, then you should make
example
a child of the media type keyword:
paths:
/users:
post:
summary: Adds a new user
requestBody:
content:
application/json: # Media type
schema: # Request body contents
$ref: '#/components/schemas/User' # Reference to an object
example: # Child of media type because we use $ref above
# Properties of a referenced object
id: 10
name: Jessica Smith
responses:
'200':
description: OK
This is needed because
$ref
overwrites all the siblings alongside it. If needed, you can use multiple examples:
paths:
/users:
post:
summary: Adds a new user
requestBody:
content:
application/json: # Media type
schema: # Request body contents
$ref: '#/components/schemas/User' # Reference to an object
examples: # Child of media type
Jessica: # Example 1
value:
id: 10
name: Jessica Smith
Ron: # Example 2
value:
id: 11
name: Ron Stewart
responses:
'200':
description: OK
Here is an example of the
example
in response bodies:
responses:
'200':
description: A user object.
content:
application/json:
schema:
$ref: '#/components/schemas/User' # Reference to an object
example:
# Properties of the referenced object
id: 10
name: Jessica Smith
Multiple examples in response bodies:
responses:
'200':
description: A user object.
content:
application/json:
schema:
$ref: '#/components/schemas/User' # Reference to an object
examples:
Jessica:
value:
id: 10
name: Jessica Smith
value:
id: 20
name: Ron Stewart
Note:
The examples in response and request bodies are free-form, but are expected to be compatible with the body schema.
Object and Property Examples
You can also specify examples for objects and individual properties in the
components
section.
Property-level example:
components:
schemas:
User: # Schema name
type: object
properties:
type: integer
format: int64
example: 1 # Property example
name:
type: string
example: New order # Property example
Object-level example:
components:
schemas:
User: # Schema name
type: object
properties:
type: integer
name:
type: string
example: # Object-level example
id: 1
name: Jessica Smith
Note that schemas and properties support single
example
but not multiple
examples
.
Array Example
You can add an example of an individual array item:
components:
schemas:
ArrayOfInt:
type: array
items:
type: integer
format: int64
example: 1
or an array-level example containing multiple items:
components:
schemas:
ArrayOfInt:
type: array
items:
type: integer
format: int64
example: [1, 2, 3]
If the array contains objects, you can specify a multi-item example as follows:
components:
schemas:
ArrayOfUsers:
type: array
items:
type: object
properties:
type: integer
name:
type: string
example:
- id: 10
name: Jessica Smith
- id: 20
name: Ron Stewart
Note that arrays and array items support single
example
but not multiple
examples
.
Examples for XML and HTML Data
To describe an example value that cannot be presented in JSON or YAML format, specify it as a string:
content:
application/xml:
schema:
$ref: '#/components/schemas/xml'
examples:
summary: A sample XML response
value: '<objects><object><id>1</id><name>new</name></object><object><id>2</id></object></objects>'
text/html:
schema:
type: string
examples:
html:
summary: A list containing two items
value: '<html><body><ul><li>item 1</li><li>item 2</li></ul></body></html>'
You can find information on writing multiline string in YAML in this Stack Overflow post:
https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines
.
External Examples
If a sample value cannot be inserted into your specification for some reason, for instance, it is neither YAML-, nor JSON-conformant, you can use the
externalValue
keyword to specify the URL of the example value. The URL should point to the resource that contains the literal example contents (an object, file or image, for example):
content:
application/json:
schema:
$ref: '#/components/schemas/MyObject'
examples:
jsonObject:
summary: A sample object
externalValue: 'http://example.com/examples/object-example.json'
application/pdf:
schema:
type: string
format: binary
examples:
sampleFile:
summary: A sample file
externalValue: 'http://example.com/examples/example.pdf'
Reusing Examples
You can define common examples in the
components/examples
section of your specification and then re-use them in various parameter descriptions, request and response body descriptions, objects and properties:
content:
application/json:
schema:
$ref: '#/components/schemas/MyObject'
examples:
objectExample:
$ref: '#/components/examples/objectExample'
components:
examples:
objectExample:
value:
id: 1
name: new object
summary: A sample object
