Search Topics

Search across all FastAPI topics

GitHub

Auto-Generated Docs

Fundamentals

"Where are the docs?" "Read the code." That conversation ends careers. FastAPI makes sure it never has to happen.

You hand a frontend developer your API. They ask: 'Where are the docs?' You say: 'Read the code.' They stare at you. This collaboration is going nowhere.

terminal
GET /docs → 200 OK

[Empty Swagger UI with no endpoints documented]

vs.

GET /docs → 200 OK

[Rich Swagger UI: 15 endpoints, request/response schemas, examples, auth flows]

Question

What if your docs wrote themselves? What if every time you added an endpoint, the documentation updated automatically — with the right parameters, the right types, and a "Try it out" button? That's not a fantasy. That's what FastAPI does out of the box.

How FastAPI Generates Docs

FastAPI reads your Python code — your type hints, Pydantic models, and endpoint decorators — and automatically generates an OpenAPI schema. That schema powers two interactive documentation UIs.

Type Hints

int, str, List[Item]

Pydantic Model

Request/response shapes

OpenAPI Schema

JSON spec (auto-generated)

Swagger UI / ReDoc

Interactive docs

How docs work

What you just learned

FastAPI generates documentation from your code — no extra files to maintain

Type hints and Pydantic models are the source of truth for your docs

You get two UIs for free: Swagger UI (/docs) and ReDoc (/redoc)

Why This Is FastAPI's Killer Feature

Most frameworks make you write docs separately from your code. That means your docs are always slightly out of date. Someone adds a parameter and forgets to update the docs. Someone changes a response shape and the docs still show the old one.

FastAPI flips this: it automatically generates interactive, up-to-date documentation directly from your endpoint definitions, type hints, and Pydantic models. No extra work, no drift between code and docs.

Preview: Code to Docs

See how Python type hints automatically become interactive Swagger UI documentation.

Swagger UI (/docs)

This is your go-to during development. It's available at /docs by default, and it lets you explore endpoints, see parameters, send real requests, and inspect responses — all from your browser. No Postman needed.

terminal
# Start your app
uvicorn main:app --reload

# Open your browser to:
# http://localhost:8000/docs
#
# You'll see every endpoint, every parameter,
# and a "Try it out" button for each one.

Insight

Pro tip: share the /docs URL with your frontend team. They can test your endpoints, see exactly what shape the data comes in, and even generate client code from it. It's way better than a Slack message saying "the endpoint returns a list of objects."

ReDoc (/redoc)

ReDoc is the other documentation UI, available at /redoc. Same data, cleaner layout. It's better for reading through your API documentation top to bottom. Some teams use Swagger for testing and ReDoc for sharing.

Customizing Your Docs

You can customize the title, description, version, and even the URLs. Want to disable docs in production? Set the URL to None.

main.py
from fastapi import FastAPI

app = FastAPI(
    title="My Awesome API",
    description="A production-ready API built with FastAPI",
    version="1.0.0",
    docs_url="/docs",        # Swagger UI (default)
    redoc_url="/redoc",      # ReDoc (default)
    # docs_url=None,         # Set to None to disable
)

Making Your Docs Actually Useful

Auto-generated docs are great. But you can make them amazing by adding descriptions, summaries, and examples. FastAPI pulls all of this from your Python code — docstrings, parameter descriptions, everything.

main.py
@app.get(
    "/items/{item_id}",
    summary="Get a single item",  # Shows in the endpoint list
    tags=["Items"],               # Groups endpoints in the sidebar
)
async def get_item(item_id: int):
    """
    Retrieve an item by its ID.

    - **item_id**: The unique identifier of the item

    Returns the full item object including price and tags.
    """
    return {"item_id": item_id}

# Your docstring becomes the detailed description in Swagger UI.
# Markdown formatting works!

Using the docs

What you just learned

Swagger UI (/docs) is interactive — you can test endpoints right from the browser

ReDoc (/redoc) is better for reading — same data, cleaner layout

Docstrings and summaries make your auto-generated docs genuinely useful

You can disable docs in production with docs_url=None

Think about it...

If you add a description parameter to your Pydantic field, where exactly does it appear in Swagger UI?

Hint: Think about where Pydantic models show up in the OpenAPI spec...

Key Points

/docs for Swagger UI

Interactive documentation with a "Try it out" button for live testing

/redoc for ReDoc

Clean, readable alternative documentation layout

Customize via FastAPI() Params

Set title, description, version, and doc URLs on the app instance

Docstrings Become Descriptions

Python docstrings on endpoint functions appear in the generated docs

These are the patterns that trip up developers most often. Switch between Wrong and Fixed to compare the code side by side.

1
Not adding type hints to parameters
Missing types means the docs can't show parameter details
Don't do this
main.py
@app.get("/items/{item_id}")
async def get_item(item_id):  # No type hint!
    return {"item_id": item_id}
# Docs show item_id as "string" with no validation
FastAPI uses type hints to generate accurate documentation AND validate input. Without types, the docs are vague and there's no automatic validation.
2
Disabling docs in development
Setting docs_url=None while still building the API
Don't do this
main.py
app = FastAPI(
    docs_url=None,   # Disabled!
    redoc_url=None,  # Also disabled!
)
# Now you can't test endpoints interactively
Only disable docs in production. During development, /docs is your best friend for testing endpoints. Use environment variables to control visibility per environment.