How to Use Summary and Description in FastAPI for API Documentation

In FastAPI, you use the summary and description parameters in path operation decorators like @app.get() to add brief and detailed explanations for your API endpoints. These help generate clear, user-friendly documentation in the automatic OpenAPI docs.

Syntax

Use summary for a short title of the endpoint and description for a detailed explanation inside the path operation decorator.

Example parameters:

• summary: A brief, one-line summary of the endpoint.
• description: A longer, detailed explanation that can include multiple lines.

python

@app.get("/items/{item_id}", summary="Get an item", description="Retrieve an item by its ID with detailed info.")
async def read_item(item_id: int):
    return {"item_id": item_id}

Example

This example shows how to add summary and description to a FastAPI endpoint. The summary appears as a short title in the docs, and the description shows more details below it.

python

from fastapi import FastAPI

app = FastAPI()

@app.get(
    "/items/{item_id}",
    summary="Get an item by ID",
    description="Retrieve an item by its unique ID. Returns the item details if found."
)
async def read_item(item_id: int):
    return {"item_id": item_id, "name": "Sample Item"}

Output

Open http://127.0.0.1:8000/docs to see the endpoint with summary and description in the API docs.

Common Pitfalls

Common mistakes include:

• Using summary and description inside the function instead of the decorator.
• Making the summary too long; it should be brief.
• Not using multiline strings for longer descriptions, which can cause formatting issues.

python

from fastapi import FastAPI

app = FastAPI()

# Wrong: summary inside function (ignored by FastAPI)
@app.get("/wrong")
async def wrong_usage():
    summary = "This won't show in docs"
    return {"msg": "wrong"}

# Right: summary and description in decorator
@app.get(
    "/right",
    summary="Correct usage",
    description="This description will appear in the docs."
)
async def right_usage():
    return {"msg": "right"}

Quick Reference

Summary and description help make your API docs clear and user-friendly. Use them wisely:

• summary: Short, one-line title for the endpoint.
• description: Longer, detailed explanation with examples or notes.
• Place both inside the path operation decorator like @app.get().
• Use triple quotes """ for multiline descriptions.

Key Takeaways

Add summary and description inside FastAPI path operation decorators to improve API docs.

Use summary for a brief title and description for detailed explanations.

Place them as parameters in decorators like @app.get(), not inside the function body.

Use multiline strings for longer descriptions to keep formatting clean.

Check your docs at /docs to see how summary and description appear.