Response Documentation

Learn the fundamentals of response documentation in FastAPI.

🎯 Core Concept

FastAPI automatically generates API documentation from response models. By defining clear response models, your API documentation in Swagger UI and ReDoc becomes detailed and useful for API consumers.

📖 What You'll Learn

In this section, you'll understand:

• How response models auto-generate documentation

• Adding descriptions to fields and models

• Using Field() for enhanced documentation

• Documenting examples with response_example

• OpenAPI response schemas

💡 Simple Example

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class Item(BaseModel):
    id: int = Field(..., description="The item's unique identifier")
    name: str = Field(..., description="The name of the item")
    price: float = Field(..., description="Price in USD", gt=0)
    description: str = Field(None, description="Optional item description")

@app.get("/items/{item_id}", response_model=Item)
async def get_item(item_id: int):
    return {"id": item_id, "name": "Widget", "price": 9.99}

Model Documentation

class Item(BaseModel):
    """An item in the inventory system"""
    id: int
    name: str
    price: float
    in_stock: bool = True

    class Config:
        json_schema_extra = {
            "example": {
                "id": 1,
                "name": "Widget",
                "price": 9.99,
                "in_stock": True
            }
        }

Response with Documentation

@app.get(
    "/items",
    response_model=List[Item],
    summary="Get all items",
    description="Retrieve a complete list of items in inventory"
)
async def list_items():
    return [...]

🔑 Key Takeaways

• ✅ Understand the purpose of response documentation

• ✅ Know when to apply this pattern

• ✅ Recognize its benefits in real-world scenarios

• ✅ Be prepared to use it in your projects

Ready to explore more? Check out the advanced section for production patterns and edge cases.