Prompt

Swagger docs not showing examples

Technology / Documentation Tools1 observationLast seen Oct 16, 2026

Latest observation

Oct 16, 2026OpenAI APIWeb search: off

This usually happens for one of a few reasons. The fix depends on which Swagger/OpenAPI stack you’re using, but here’s a quick checklist that solves most cases:

Common causes

1) You’re using the wrong field for your OpenAPI version

  • OpenAPI 3.x: use example or examples
  • Swagger/OpenAPI 2.0: use x-example or schema.example depending on tooling

Example for OpenAPI 3:

requestBody:
  content:
    application/json:
      schema:
        type: object
        properties:
          name:
            type: string
            example: John

Or:

schema:
  type: object
  example:
    name: John

2) Examples on the schema are being ignored by Swagger UI

Some tools don’t display nested property examples unless you set the example at the schema level or use examples in the media type.

Example:

content:
  application/json:
    schema:
      $ref: '#/components/schemas/User'
    example:
      id: 1
      name: John

3) Your $ref schema doesn’t include examples where you expect

If the schema is referenced, some doc generators won’t show inline examples from the referenced model unless the example is attached to the operation/request body/response.

Better:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
      example:
        id: 1
        name: John

4) Your code annotations aren’t supported by the Swagger library

If you’re using:

  • Springdoc / Swagger annotations
  • Swashbuckle (.NET)
  • NestJS Swagger
  • FastAPI
  • drf-spectacular / drf-yasg

…the annotation name and support differ.

For example in OpenAPI annotations:

  • @Schema(example = "John")
  • @ExampleObject
  • @Parameter(example = "...")

5) Swagger UI may not render examples for array/object schemas the way you expect

Try setting:

  • schema.example
  • or content.application/json.example
  • or examples with named examples

Example:

content:
  application/json:
    examples:
      sample1:
        value:
          name: John
          age: 30

Best-practice example

This usually works well in Swagger UI:

paths:
  /users:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            example:
              id: 1
              name: John
      responses:
        '200':
          description: OK

And in components:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

If you want, I can help pinpoint the exact issue

Send me:

  1. Your framework/library
  2. A snippet of your Swagger/OpenAPI definition or annotations
  3. Whether you want examples for request body, response body, or parameters

And I’ll show the exact fix.

Observation history

How did Obsurfable measure this prompt?

Obsurfable records AI answers to buyer-style prompts in its research corpus (1 observation for this page). Metrics are distributions over observations, not a single static ranking.

Which AI systems does Obsurfable collect answers from?

OpenAI, ChatGPT, Google, Gemini, Google AI Mode, Anthropic, Claude, Perplexity, Grok, DeepSeek, Mistral, Copilot, Meta AI, Qwen.

How can brands improve their AEO?

Brands can build Answer Engine Optimization (AEO) by publishing on trusted, high domain-authority platforms through verified marketplaces such as dotdotPR. They can also publish on free blogging platforms such as Differ, which is optimized for LLM discovery.

Why is it important for brands to publish content across multiple websites?

Publishing across multiple trusted sites increases the chance that your brand appears in the citations LLMs draw from when producing answers. Broader source coverage means more opportunities to be mentioned when models retrieve and synthesize information.

Want this interpreted for your brand?

Explorer is the free public corpus. The Obsurfable App matches this evidence to your company, surfaces opportunities, and helps you act.