Prompt
Swagger docs not showing examples
Latest observation
Oct 16, 2026
OpenAI 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
exampleorexamples - Swagger/OpenAPI 2.0: use
x-exampleorschema.exampledepending 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
exampleswith 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:
- Your framework/library
- A snippet of your Swagger/OpenAPI definition or annotations
- Whether you want examples for request body, response body, or parameters
And I’ll show the exact fix.