Prompt
Why does Swagger UI not show my schemas?
Latest observation
Swagger UI usually doesn’t show schemas for one of a few common reasons:
1) The schema isn’t actually in the OpenAPI spec
Swagger UI only renders what it receives from your generated OpenAPI document. If your framework didn’t include the model, it won’t appear.
Check the raw spec first:
openapi.jsonswagger.json/v3/api-docs- whatever endpoint your app exposes
Look for:
components.schemas- or
definitionsin older Swagger/OpenAPI versions
If it’s missing there, the issue is in your backend/OpenAPI generation, not Swagger UI.
2) Your endpoints don’t reference the schema
A schema can exist in the document but not be displayed prominently if no request/response uses it.
Example:
- Defined in
components.schemas - But no endpoint has
requestBody/responsespointing to it
Swagger UI often shows schemas best when they’re actually used by an operation.
3) The model is not annotated or registered correctly
Depending on your stack, you may need to explicitly register or annotate models.
Examples:
- Springdoc / Spring Boot: ensure DTOs are used in controller signatures
- Swashbuckle / ASP.NET Core: ensure types are referenced and
c.SchemaFilterisn’t removing them - FastAPI: use Pydantic models as request/response types
- NestJS: use
@ApiProperty()/@ApiExtraModels()when needed
4) The spec has errors and Swagger UI fails to render parts of it
Invalid OpenAPI can cause sections to disappear or render incorrectly.
Check browser dev tools:
- Console errors
- Failed network requests
- CORS issues
Also validate the OpenAPI JSON using:
- Swagger Editor
- OpenAPI validator
5) You’re looking at the wrong place in Swagger UI
Schemas are usually under:
- Schemas
- Models
- or at the bottom of the page depending on version/theme
If you only see endpoints, expand the Schemas section.
6) The OpenAPI version/framework configuration hides them
Some setups require enabling schema display or setting package scanning correctly.
Examples:
- wrong package scan
includeSchemas/showExtensionssettings- filtering out internal models
- custom serializer naming causing conflicts
7) Circular references or unsupported types
Complex models can break schema generation:
- circular dependencies
- generic types not supported by your generator
- maps/dictionaries with unusual keys
- polymorphism not configured correctly
Quick debugging checklist
- Open the raw OpenAPI JSON
- Confirm the schema exists in
components.schemas - Confirm at least one endpoint references it
- Check browser console for Swagger UI errors
- Validate the spec in Swagger Editor
If you want, paste:
- your framework/language
- a sample model/controller
- the generated OpenAPI snippet
and I can tell you exactly why Swagger UI isn’t showing the schemas.