OpenAPI Examples; A Practical Guide

May 5, 2026

OpenAPI Examples

Examples are a great way to show what data your API expects or responds with using real world examples. This can be especially useful when you want to highlight edge cases or show how data is serialized in locations such as a path's query. We're going to break down OpenAPI examples in parameters, schemas, and responses and requests based on the OpenAPI 3.2.X specification (which is backwards compatible with OpenAPI 3.1.X).

This article is a practical guide to using examples in OpenAPI 3.2.X (and 3.1.X). If you want a more comprehensive understanding, you can read the OpenAPI's working with examples section for more details .

Is it Example of Examples?

In OpenAPI, there is the example field and the examples field. For Schemas, examples should be used, with the singular example field deprecated as of OpenAPI 3.2.0. (You can find more information in the Fixed Fields section of the Schema Object section in the OpenAPI's 3.2.0 specification page here)

As for Parameters, Request Bodies, and Responses, example is the shorthand singular version of examples and only contains the value property.

In this article, I'll be focusing on the examples field since it is more versatile and comprehensive.

Examples in Schemas

Examples in schemas are very straightforward. Under examples, you can provide an array of examples that conform to the schema. That's it! Nice and simple. The example below contains 2 examples for a "Product" schema, one with a description, and one without one (since it isn't a required field).

components:
  schemas:
    Products:
      title: Products
      type: object
      required:
        - id
        - name
        - sellingPrice
        - weight
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
        description:
          type: string
        sellingPrice:
          type: number
        weight:
          type: number
      examples:
        - id: prod_iofnawi32nf
          name: Apple Juice
          sellingPrice: 100
          weight: 10
        - id: prod_jfi8eurj23j
          name: Orange Juice
          description: Enjoy a refreshing box of orange juice!
          sellingPrice: 90
          weight: 10

Examples in Parameters

Examples for "Parameters" are more involved than Schema examples. For example, they:

1. Are named
2. Can have a summary and a description
3. The example data is described via the value property
4. A serializeValue exists to show how dataValue is encoded when special characters are used, or when special encoding is needed to render dataValue in query parameters.

The last point is particularly helpful. It can be difficult to know how data should be encoded in requests. Providing a serializeValuecan resolve any ambiguity. For example, the sample below shows how the search query can be used to search for products ending with "juice" and how it would be encoded.

name: search
in: query
schema:
  type: string
  x-restly:
    id: 42d6ec51-1a83-49a2-8e35-b61b477e8705
  example: ""
examples:
  endingWithJuice:
    dataValue: '% juice'
    serializeValue: '%25%20juice'

Examples in Requests and Responses

Examples in Requests and Responses are the same as examples in parameters. They are named and can can contain the dataValue andserializeValue properties. What is particularly useful about examples in responses is you can describe expected error flows with great fidelity without over-complicating your schema definitions.

For example, the below sample contains an endpoint for getting a product. In the 404 response, we can provide an example of what the response actually looks like, and include the appropriate status code for this response. Instead of embeding the error code in the Error schema, which can grow unwieldy, we can provide examples of what status codes the API client may bump into at the operation level.

paths:
  /products:
    get:
      summary: List Products
      responses:
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                productNotFound:
                  dataValue:
                    code: "11233"
                    message: product not found

Restly Now Supports Examples

Restly now supports all the above examples through the API designer interface. You can set schema examples, parameter examples, and request and response examples natively. In addition, these examples will be exported when you generate an OpenAPI 3.2.X schema file, and imported when you create an API from a spec file.