OpenAPI Examples: A Practical Guide

By Restly Labs

Published May 5, 2026Updated July 21, 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 schemas, parameters, requests, and responses using the OpenAPI 3.2 specification.

This article uses the OpenAPI 3.2 fields dataValue and serializedValue. For Example Objects, OpenAPI 3.1 uses the older value and externalValue fields instead. For the complete 3.2 rules, read the OpenAPI working-with-examples section.

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 in OpenAPI 3.1 and still deprecated in 3.2. See the OpenAPI 3.2 Schema Object section.

Parameter, Header, and Media Type Objects can use the singular example shorthand or an examples map of named Example Objects. The two fields are mutually exclusive.

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:

Are named
Can have a summary and a description
dataValue holds the value in the form that is validated against the schema
serializedValue shows the exact string produced after the parameter's style, explode, and encoding rules are applied

The last point is particularly helpful. It can be difficult to know how data should be encoded in requests. Providing a serializedValue can 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
examples:
  endingWithJuice:
    dataValue: '% juice'
    serializedValue: 'search=%25%20juice'

Examples in Requests and Responses

Request and response examples live under a Media Type Object in the operation's content map. Named Example Objects can contain the dataValue and serializedValue 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 embedding 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.

Try Restly for Free