How can I use OpenAPI overlays to add examples to an existing OpenAPI document?

How can I use OpenAPI overlays to add examples to an existing OpenAPI document? #

Good API documentation depends heavily on realistic request and response examples, but authoring those examples is often a separate effort from designing the schema itself. Rather than cluttering your canonical OpenAPI document with example payloads as soon as they’re written, you can maintain them in a dedicated Overlay Specification file and merge them in only when producing documentation.

Why Separate Examples From the Base Document #

Teams frequently iterate on documentation examples much faster than they iterate on the underlying schema. Keeping examples in an overlay:

Lets writers and developer-advocates update examples without touching the API contract.
Allows different example sets for different audiences (e.g., “quickstart” examples vs. exhaustive edge-case examples).
Keeps pull requests to the base spec focused on the contract itself.

Targeting Response and Request Bodies #

The update action performs a deep merge (RFC 7396-style), so you can add an examples key without disturbing the rest of the schema:

overlay: 1.0.0
info:
  title: Add Documentation Examples
  version: 1.0.0
actions:
  - target: $.paths['/users/{id}'].get.responses['200'].content['application/json']
    update:
      examples:
        default:
          summary: A typical user record
          value:
            id: "usr_9F82"
            name: "Ada Lovelace"
            email: "ada@example.com"
            createdAt: "2026-01-15T10:00:00Z"

Adding Examples to Request Bodies #

The same pattern applies to requestBody content:

  - target: $.paths['/orders'].post.requestBody.content['application/json']
    update:
      examples:
        minimal:
          summary: Minimal valid order
          value:
            productId: "prod_123"
            quantity: 1
        withNotes:
          summary: Order with optional notes
          value:
            productId: "prod_123"
            quantity: 2
            notes: "Gift wrap please"

Adding Multiple Named Examples per Operation #

The OpenAPI examples object supports multiple named examples per media type, which is ideal for showing both a “happy path” and one or more edge cases:

  - target: $.paths['/payments'].post.responses['422'].content['application/json']
    update:
      examples:
        insufficientFunds:
          summary: Card declined due to insufficient funds
          value:
            error: "insufficient_funds"
            message: "The card was declined."
        expiredCard:
          summary: Expired card
          value:
            error: "expired_card"
            message: "The card has expired."

Targeting Many Operations at Once #

If you want to add a generic example to every 404 response across the whole document, JSONPath’s wildcard support makes this concise:

  - target: $.paths.*.*.responses['404'].content['application/json']
    update:
      examples:
        notFound:
          summary: Resource not found
          value:
            error: "not_found"
            message: "The requested resource could not be located."

Note that wildcard support for deeply nested merges can vary between overlay implementations, so always validate the result with your tooling before publishing.

Applying the Overlay #

redocly join openapi.yaml --overlay examples-overlay.yaml -o openapi.with-examples.yaml

The resulting document can be fed directly into a documentation renderer such as Redoc or Swagger UI, both of which display the examples object prominently.

Keeping Examples in Sync #

Since the base schema and the examples overlay are independent files, add a validation step in CI that checks each example against its corresponding schema (many linters, including Spectral, support this). This prevents the overlay from silently drifting out of sync as the schema evolves.

See What is the OpenAPI Overlay Specification? for the full action model, and How can I use OpenAPI overlays to enrich schemas with additional validation rules? for a related technique.

Last updated on July 16, 2026.