OAS 2 This page applies to OpenAPI Specification ver. 2 (fka Swagger).
To learn about the latest version, visit OpenAPI 3 pages.
Adding Examples
An API specification can include examples for:
- response MIME types,
- schemas (data models),
- individual properties in schemas.
Examples can be used by tools and libraries, for instance, Swagger UI auto-populates request bodies based on input schema examples, and some API mocking tools use examples to generate mock responses.
Note: Do not confuse example values with the default
values. An example is used to illustrate what the value is supposed to be like. A default value is something that the server uses if the value is not provided in the request.
Schema Examples
The example
key is used to provide a schema example. Examples can be given for individual properties, objects and the whole schema.
Property Examples
Property examples can be specified inline. The example value must conform to the property type.
definitions:
CatalogItem:
type: object
properties:
id:
type: integer
example: 38
title:
type: string
example: T-shirt
required:
- id
- title
Note that multiple example values per property or schema are not supported, that is, you cannot have:
title:
type: string
example: T-shirt
example: Phone
Object Examples
Properties of a type object can have complex inline examples that include that object’s properties. The example should comply with the object schema.
definitions:
CatalogItem:
type: object
properties:
id:
type: integer
example: 38
title:
type: string
example: T-shirt
image:
type: object
properties:
url:
type: string
width:
type: integer
height:
type: integer
required:
- url
example: # <-----
url: images/38.png
width: 100
height: 100
required:
- id
- title
Array Examples
An example for an array of primitives:
definitions:
ArrayOfStrings:
type: array
items:
type: string
example:
- foo
- bar
- baz
Similarly, an array of objects would be specified as:
definitions:
ArrayOfCatalogItems:
type: array
items:
$ref: '#/definitions/CatalogItem'
example:
- id: 38
title: T-shirt
- id: 114
title: Phone
Whole Schema Examples
An example
can be specified for the entire schema (including all nested schema), provided that the example conforms to the schema.
definition:
CatalogItem:
type: object
properties:
id:
type: integer
name:
type: string
image:
type: object
properties:
url:
type: string
width:
type: integer
height:
type: integer
required:
- id
- name
example: # <----------
id: 38
name: T-shirt
image:
url: images/38.png
width: 100
height: 100
Response Examples
Swagger allows examples on the response level, each example corresponding to a specific MIME type returned by the operation. Such as one example for application/json
, another one for text/csv
and so on. Each MIME type must be one of the operation’s produces
values -- either explicit or inherited from the global scope.
produces:
- application/json
- text/csv
responses:
200:
description: OK
examples:
application/json: { "id": 38, "title": "T-shirt" }
text/csv: >
id,title
38,T-shirt
All examples are free-form, meaning their interpretation is up to tools and libraries.
JSON and YAML Examples
Since JSON and YAML are interchangeable (YAML is a superset of JSON), both can be specified either using the JSON syntax:
examples:
application/json:
{
"id": 38,
"title": "T-shirt"
}
or the YAML syntax:
examples:
application/json:
id: 38
title: T-shirt
image:
url: images/38.png
XML Examples
There is no specific syntax for XML response examples. But, since the response examples are free-form, you can use any format that you wish or that is supported by your tool.
examples:
application/xml: '<users><user>Alice</user><user>Bob</user></users>'
examples:
application/xml:
users:
user:
- Alice
- Bob
examples:
application/xml:
url: http://myapi.com/examples/users.xml
Alternatively, you can specify the example values in the response schema, as explained above.
Text Examples
Since all response examples are free-form, you can use any format supported by your tool or library. For instance, something like:
examples:
text/html: '<html><body><p>Hello, world!</p></body></html>'
text/plain: Hello, world!
See also this post on Stack Overflow for tips on how to write multi-line strings in YAML.
Example Precedence
If there are multiple examples on different levels (property, schema, response), the higher-level example is used by the tool that is processing the spec. That is, the order of precedence is:
- Response example
- Schema example
- Object and array property examples
- Atomic property examples and array item examples
Examples and $ref
OpenAPI 2.0 example
and examples
keywords require inline examples and do not support $ref
. The example values are displayed as is, so $ref
would be displayed as an object property named $ref
.
Referencing examples is supported in OpenAPI 3.0.
Did not find what you were looking for? Ask the community
Found a mistake? Let us know