Every API team says the spec is the source of truth, then maintains five copies of what a response actually looks like: one in the docs, one in a mock server, one in a shared collection, one in test fixtures, and one in the prompt context given to an AI assistant. Within a quarter they disagree. The docs show a field the API no longer returns, the mock invents an envelope the real service never wraps in, and the agent confidently calls a shape that 404s. The fix is not better discipline around copying; it is having one place where examples live and generating every other surface from it.

Examples are first-class in OpenAPI

A schema says a field is a string; an example shows that order ids look like ord_8f3a2c, that money is returned as a decimal string, and that a status enum actually serializes to lowercase. OpenAPI lets you attach named examples at the media type and parameter level, which is more useful than a single inline example because you can show the cases a consumer must handle:

paths:
  /orders:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateOrderRequest" }
            examples:
              minimal:
                summary: One item, no note
                value:
                  items: [{ sku: "sku-001", quantity: 1 }]
                  currency: "USD"
              full:
                summary: Multiple items with a note
                value:
                  items:
                    - { sku: "sku-001", quantity: 2 }
                    - { sku: "sku-014", quantity: 1 }
                  currency: "USD"
                  note: "Leave at the front desk"
      responses:
        "201":
          description: Order created
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }
              examples:
                created:
                  value:
                    id: "ord_8f3a2c"
                    status: "pending"
                    total: { amount: "129.00", currency: "USD" }
        "422":
          description: Validation failed
          content:
            application/problem+json:
              examples:
                invalidCurrency:
                  value:
                    type: "https://api.example.com/problems/invalid-input"
                    status: 422
                    title: "Unprocessable Entity"
                    errors:
                      - { field: "currency", code: "unsupported_currency" }

Parameters carry examples too, which is where realistic filter and pagination values belong. Do not forget the empty state: a list endpoint needs an example with an empty array and the correct pagination envelope, because "no results" is a response every client renders and almost no one documents.

A good example passes four tests

Most "example drift" is really example quality failure. Each example should be:

  • Schema-valid. It must validate against the schema it sits next to, including required fields, enum values, formats, and nullability. An example that violates the schema is the most dangerous kind of documentation, because it is the part developers copy verbatim.
  • Realistic. Use values with the right shape and meaning (ord_8f3a2c, ISO timestamps, ISO 4217 currencies), not test, 123, and string. Consumers infer semantics from examples that schemas cannot express.
  • Representative of branches. Cover the happy path, the empty result, and the documented errors. Boundary cases such as a one-item list and a page at the end of the result set are worth their own examples.
  • Safe. Never include real tokens, customer PII, or production identifiers; use obviously synthetic but well-formed data.

The schema still carries the constraints. Examples illustrate; they do not replace required, minimum, enum, or pattern. When the two disagree, the schema is the contract and the example is a bug to fix.

Render the same examples everywhere

Once examples live in the spec, the other surfaces become views over them rather than separate artifacts:

                         OpenAPI spec (schemas + examples)
                          /      |        |          \
                   rendered    mock     scenario    typed clients /
                    docs      server    tests        agent tool context
  • Documentation renders the named examples with language tabs and try-it requests, so the snippets readers copy are the exact reviewed payloads.
  • Mock servers answer from the schema and its examples before the backend exists; a 422 example becomes a reachable error response instead of an untested afterthought.
  • Scenario tests use request examples as inputs and assert against documented response examples, chaining the captured values into user journeys.
  • Generated clients ship the same field names and types, eliminating hand-copied DTOs.
  • Agent and MCP tooling reads examples to disambiguate what schemas leave open, the exact enum spelling, the pagination wrapper, and the error envelope. Models follow a concrete, valid example far more reliably than a prose description, which measurably reduces bad tool arguments.

This is the single-source-of-truth loop: edit one example in the spec and the docs, mock, tests, and agent context all move together.

Enforce honesty in CI

Examples that are not validated rot, so make them part of the contract checks:

  • Validate every example against its media-type schema in CI, including error and empty examples; fail the build on mismatch.
  • Diff examples on schema changes so a new required field forces an update to every documented payload.
  • Confirm each documented error status has an example, not just a description string.
  • Keep examples free of secrets with the same scanner used for source code.
  • When the spec is scanned from code, preserve hand-authored examples on rescan rather than overwriting them; they are documentation the scanner cannot infer.

Treat an invalid example as a defect of the same severity as an invalid schema. Both generate broken clients; the example just does it more convincingly.

Start small

You do not need exhaustive examples on day one. For each operation, document one realistic success payload, one empty or boundary payload where a collection is involved, and the most likely validation error. Name them by the situation they represent rather than "example one", and let the mock and docs pick them up automatically. That minimal set already removes the four-way copy-paste that causes most integration bugs.

The Powerduck workflow is built around this loop: design schemas and examples in one local spec, render docs, drive mocks and scenario tests, and expose the same contract to agents, with hand-authored examples preserved across rescans. See how mocks behave when they are fed a real spec in the OpenAPI mock server comparison, how scenarios consume these examples in scenario testing for REST APIs, and the end-to-end loop in the online demo.