FastAPI OpenAPI Examples Fix
In this tutorial, you'll learn about FastAPI OpenAPI Examples Fix. We cover key concepts, practical examples, and best practices.
The Problem
FastAPI generates API docs from Pydantic models, but the schemas show type information only. API consumers need concrete examples to understand the expected data format.
Quick Fix
Wrong — no examples in schema
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
category: str
Output: Swagger UI shows field types (string, number) but no examples. Users don't know what values are valid.
Correct — Field with examples
from pydantic import BaseModel, Field
class Item(BaseModel):
name: str = Field(examples=["Wireless Mouse"])
price: float = Field(examples=[29.99])
category: str = Field(examples=["Electronics"])
class ItemCreate(BaseModel):
name: str = Field(examples=["Ergonomic Keyboard"])
price: float = Field(examples=[89.99])
category: str = Field(examples=["Electronics"])
Output: Swagger UI shows example values in the schema and pre-fills them in the "Try it out" section.
Config-level examples
class Item(BaseModel):
name: str
price: float
category: str
model_config = {
"json_schema_extra": {
"examples": [
{
"name": "Wireless Mouse",
"price": 29.99,
"category": "Electronics",
}
]
}
}
Multiple examples
class Item(BaseModel):
name: str
price: float
model_config = {
"json_schema_extra": {
"examples": [
{"name": "Mouse", "price": 29.99},
{"name": "Keyboard", "price": 89.99},
{"name": "Monitor", "price": 299.99},
]
}
}
Response examples
from fastapi import FastAPI
from fastapi.responses import JSONResponse
@app.get(
"/items/{item_id}",
response_model=Item,
responses={
200: {
"description": "Item found",
"content": {
"application/json": {
"example": {
"id": 1,
"name": "Wireless Mouse",
"price": 29.99,
"category": "Electronics",
}
}
},
},
404: {
"description": "Item not found",
"content": {
"application/json": {
"example": {"detail": "Item not found"}
}
},
},
},
)
async def get_item(item_id: int):
...
Body examples with OpenAPI
from fastapi import Body
@app.post("/items")
async def create_item(
item: Item = Body(
examples={
"simple": {
"summary": "Simple example",
"value": {"name": "Mouse", "price": 29.99},
},
"full": {
"summary": "Full example with all fields",
"value": {"name": "Gaming Mouse", "price": 59.99, "category": "Electronics"},
},
},
),
):
...
Prevention
- Add
examplesto every Pydantic field in request models. - Provide realistic example values — not placeholder text.
- Add response examples for error cases to document failure formats.
Common Mistakes with openapi examples
- Misunderstanding that
Stringis[Char]with poor performance for large text operations - Using
foldlinstead offoldl'causing stack overflow on large lists - Forgetting
deriving (Show, Eq)on custom data types needed for debugging
These mistakes appear frequently in real-world FASTAPI code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.
Practice Exercise
Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.
This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.
FAQ
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro