There are a few common reasons OpenAPI docs end up missing examples, even when you think you defined them.

1) The example is in the schema, but the docs UI doesn’t show it

Some UIs only display examples in certain places:

• Swagger UI may show:
  • example at the schema property level
  • examples / example at the request body or response content level
• ReDoc may render them differently or hide them in collapsible sections

So the example may be present in the spec, but the docs site doesn’t render it prominently.

2) You used the wrong OpenAPI field name

OpenAPI supports different example locations:

For a property

components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
          example: Alice

For a request/response body

requestBody:
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/User'
      example:
        name: Alice

Multiple examples

content:
  application/json:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      alice:
        value:
          name: Alice
      bob:
        value:
          name: Bob

Common mistake: putting example: in a place where the tooling expects examples: or vice versa.

3) $ref is overriding or hiding the example

If your schema is referenced with $ref, some tools ignore sibling fields next to $ref unless they’re supported by the specific OpenAPI version/tooling.

Bad in many cases:

content:
  application/json:
    schema:
      $ref: '#/components/schemas/User'
    example:
      name: Alice

Depending on the tool, that example may not render. Some generators want the example inside the referenced schema itself.

4) Your schema is generated, but examples are not included by the generator

If you're using something like:

• NestJS Swagger
• Springdoc
• Swashbuckle / ASP.NET
• FastAPI
• NSwag
• TypeScript/Java annotation-based generation

…the generator may not automatically include examples unless you explicitly annotate them.

For example, in some frameworks you need special decorators/annotations for examples rather than just describing the model.

5) The docs UI is caching an older spec

Very common.

Symptoms:

• You updated the OpenAPI spec
• Examples are in the file
• Docs site still doesn’t show them

Fixes:

• Hard refresh the browser
• Clear CDN/cache
• Restart the docs server
• Rebuild the generated spec
• Ensure the docs page is loading the latest JSON/YAML URL

6) Invalid OpenAPI structure causes the example to be ignored

If the spec is malformed, some docs tools silently skip fields.

Examples:

• example placed where examples is required
• wrong indentation in YAML
• using example under schema when the tool expects it under content
• invalid JSON Schema values

Run your spec through:

• Swagger Editor
• OpenAPI validator
• your framework’s spec linter

7) The example is there, but the “Try it out” request uses a different source

Some docs UIs generate sample payloads from the schema defaults rather than examples unless configured otherwise.

You may need:

• example
• default
• examples
• or vendor-specific config to make the UI prefer your example

8) Content type mismatch

If your example is attached to application/json but the operation uses a different content type, it won’t show.

Make sure the example is under the exact media type you’re documenting.

---

Quick checklist

Check these first:

1. Is the example in the right place?
2. Are you using example vs examples correctly?
3. Is there a $ref involved that may hide it?
4. Does your framework support examples in generated docs?
5. Is your docs UI cached?
6. Does the spec validate?

---

If you want, paste a small snippet of your OpenAPI YAML/JSON and I can point out exactly why the examples aren’t showing.