API descriptions can be rather dry and factual, producing reference documentation that is accurate but can still fail to bridge the gap between API interface and happy, productive API consumers. Adding examples to OpenAPI can go a long way to helping users understand what they can do, and how to do it. There's no replacement for quickstart guides, tutorials, and other documentation of course - but richer examples in the OpenAPI descriptions can feed documentation and other downstream tools to get users up and running fast.

The first step is to include examples for as many aspects of your OpenAPI as you can. Headers, parameters, request bodies and responses all benefit from appropriate examples. This article shows how to add examples to your API descriptions, and how to get the examples to do a little more work along the way.

Choose data that connects

Choosing meaningful data takes time and energy, but it produces results. There are very few situations where the string "foo" or the string "string" truly help a user to reach their destination with efficiency and delight. In the example below you can see some of the common fields used in the Museum API and the example values used to help the user get the correct data in each field.

    EventId:
      description: Identifier for a special event.
      type: string
      format: uuid
      example: 3be6453c-03eb-4357-ae5a-984a0e574a54
    EventPrice:
      description: Price of a ticket for the special event
      type: number
      format: float
      example: 25
    Date:
      description: ISO-formatted date value.
      type: string
      format: date
      example: 2024-02-28
    Email:
      description: Email address for ticket purchaser.
      type: string
      format: email
      example: museum-lover@example.com

Don't be too serious with your examples! It's good practice to use a reserved example like example.com for URLs and email addresses, but here we've used museum-lover@example.com and it always makes me smile!

Especially if your API has multiple similar fields, use example data as well as meaningful field descriptions to direct the user's attention. For example. we use start dates that are earlier than end dates. You could also use data such as customer@example.com and accounts-department@example.com to distinguish multiple email fields.

Add example values for object properties

For more complex values, such as objects, a great way to start is to add an example for each property. Depending which tools consume the OpenAPI description, they may make use of these. The following example shows a SpecialEvent schema with multiple object properties, where each property has an example field.

    SpecialEvent:
      description: Special museum events with ticketing.
      properties:
        name:
          description: Name of the special event
          type: string
          example: Fossil lecture
        location:
          description: Location where the special event is held
          type: string
          example: Lecture theatre
        eventDescription:
          description: Description of the special event
          type: string
          example: Our panel of experts will share their favorite fossils and explain why they are so great.
        dates:
          description: List of planned dates for the special event
          type: array
          items:
            type: string
            format: date
            example: 2024-03-29
        price:
          description: Price of a ticket for the special event
          type: number
          format: float
          example: 12.50

These values are combined by tools such as Redoc to show an example to the user of how the payload looks.

Use multiple examples for responses

We're going to skip the backstory of how it is possible that OpenAPI has both example and examples as valid keywords (Phil's writeup is good if you are curious). Suffice to say: being able to supply multiple examples is brilliant, and especially useful when there are a few different possible responses to an endpoint.

The following example shows the Museum API returning two example payloads:

      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetMuseumHoursResponse"
              examples:
                default:
                  summary: Museum opening hours
                  value:
                    - date: "2023-09-11"
                      timeOpen: "09:00"
                      timeClose: "18:00"
                    - date: "2023-09-12"
                      timeOpen: "09:00"
                      timeClose: "18:00"
                    - date: "2023-09-13"
                      timeOpen: "09:00"
                      timeClose: "18:00"
                    - date: "2023-09-17"
                      timeOpen: "09:00"
                      timeClose: "18:00"
                closed:
                  summary: The museum is closed
                  value: []

By describing the possible different payloads that the API can return, API consumers can be confident that they can test edge cases. In the example of the Museum API opening hours, if the museum is closed then there are no opening hours for a particular date entry. Adding a separate example showing an empty array if there are no opening hours in the date range specified gives users a clear message of what happens in that situation.

For more complex APIs, returning multiple response examples becomes even more useful. For example in an ecommerce system, an order schema might have diffferent data in it depending if the order is already paid for, delivered, and so on. Showing the examples goes beyond showing a list of optional data fields to clearly illustrate what the API consumer can expect.

Add linting for examples

Redocly CLI is a widely-used tool for linting OpenAPI descriptions; it has specific rules available to help check that the examples in an OpenAPI description are present and valid. Read more about setting up your own linting rules and try enabling these example-specific rules in your own projects:

• no-invalid-parameter-examples: Parameter examples must match declared schema types.
• scalar-property-missing-example: All required scalar (non-object) properties must have examples defined.
• no-invalid-schema-examples: Schema examples must match declared types.
• no-invalid-media-type-examples: Example request bodies must match the declared schema.

Examples are worth a thousand words

We're documentation fanatics, so we'd probably say that you can write the thousand words as well, but having clear examples throughout your API description takes your API user experience to the next level. This post showed how you can add examples to the various aspects of an OpenAPI file, and gave some tips for picking example values to nudge your users in the right direction.