Prompt
Why is my Swagger docs page missing request examples?
Latest observation
Oct 16, 2026
OpenAI APIWeb search: off
A Swagger UI page can miss request examples for a few common reasons:
-
Your OpenAPI spec doesn’t define them
- Swagger UI only shows examples if they’re present in the schema, request body, or parameters.
- In OpenAPI, that usually means using:
exampleexamplesschema.examplerequestBody.content...examples
-
You’re using
defaultinstead ofexampledefaultdescribes a fallback value, but Swagger UI often won’t render it as a request example.- Use
examplefor visible sample data.
-
The request body schema is too vague
- If your body is just
type: objectwith no properties/examples, Swagger UI has little to display. - Add property-level examples or a full body example.
- If your body is just
-
Your framework isn’t generating examples automatically
- Some tools generate OpenAPI docs from code annotations, but they won’t infer examples unless you explicitly add them.
- Examples may need decorators/attributes like:
- NestJS:
@ApiBody({ examples: ... }) - Springdoc/OpenAPI annotations
- Swashbuckle/NSwag annotations
- FastAPI
Body(..., example=...)
- NestJS:
-
You’re looking at a parameter example, not a JSON body example
- Query/path/header parameters use
exampleon the parameter. - Request bodies use
requestBody.content.application/json.example(s).
- Query/path/header parameters use
-
Swagger UI version/limitations
- Older Swagger UI versions may not display multiple examples as expected.
- Sometimes examples are present in the spec, but the UI only shows one or renders them differently.
What to check
- Open the raw OpenAPI JSON/YAML and search for
exampleorexamples. - If they’re absent, add them in your API documentation annotations or spec.
- If they’re present, verify the UI version and whether the example is attached to the correct section.
Example OpenAPI request body
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
examples:
basic:
value:
name: "Alice"
email: "alice@example.com"
If you want, I can help you debug this for your specific stack (NestJS, Spring Boot, FastAPI, .NET, etc.) if you paste your OpenAPI snippet or controller code.