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.

1
definitions:
2
  CatalogItem:
3
    type: object
4
    properties:
5
      id:
6
        type: integer
7
        example: 38
8
      title:
9
        type: string
10
        example: T-shirt
11
    required:
12
      - id
13
      - title

Note that multiple example values per property or schema are not supported, that is, you cannot have:

1
title:
2
  type: string
3
  example: T-shirt
4
  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.

1
definitions:
2
  CatalogItem:
3
    type: object
4
    properties:
5
      id:
6
        type: integer
7
        example: 38
8
      title:
9
        type: string
10
        example: T-shirt
11
      image:
12
        type: object
13
        properties:
14
          url:
15
            type: string
16
          width:
17
            type: integer
18
          height:
19
            type: integer
20
        required:
21
          - url
22
        example:   # <-----
23
          url: images/38.png
24
          width: 100
25
          height: 100
26
    required:
27
      - id
28
      - title

Array Examples

An example for an array of primitives:

1
definitions:
2
  ArrayOfStrings:
3
    type: array
4
    items:
5
      type: string
6
    example:
7
      - foo
8
      - bar
9
      - baz

Similarly, an array of objects would be specified as:

1
definitions:
2
  ArrayOfCatalogItems:
3
    type: array
4
    items:
5
      $ref: '#/definitions/CatalogItem'
6
    example:
7
      - id: 38
8
        title: T-shirt
9
      - id: 114
10
        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.

1
definition:
2
  CatalogItem:
3
    type: object
4
    properties:
5
      id:
6
        type: integer
7
      name:
8
        type: string
9
      image:
10
        type: object
11
        properties:
12
          url:
13
            type: string
14
          width:
15
            type: integer
16
          height:
17
            type: integer
18
    required:
19
      - id
20
      - name
21
    example:   # <----------
22
      id: 38
23
      name: T-shirt
24
      image:
25
        url: images/38.png
26
        width: 100
27
        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.

1
produces:
2
  - application/json
3
  - text/csv
4
responses:
5
  200:
6
    description: OK
7
    examples:
8
      application/json: { "id": 38, "title": "T-shirt" }
9
      text/csv: >
10
        id,title
11
        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:

1
examples:
2
  application/json:
3
    {
4
      "id": 38,
5
      "title": "T-shirt"
6
    }

or the YAML syntax:

1
examples:
2
  application/json:
3
    id: 38
4
    title: T-shirt
5
    image:
6
      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.

1
examples:
2
  application/xml: '<users><user>Alice</user><user>Bob</user></users>'
3

4
examples:
5
  application/xml:
6
    users:
7
      user:
8
        - Alice
9
        - Bob
10

11
examples:
12
  application/xml:
13
    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:

1
examples:
2
  text/html: '<html><body><p>Hello, world!</p></body></html>'
3
  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