FastAPI Automatic Interactive Docs

FastAPI generates two documentation pages for your API with zero extra code. These pages let you read about your endpoints and test them directly in the browser. This saves time during development and makes sharing your API with teammates much easier.

The Two Documentation Pages

Swagger UI — at /docs

Visit http://127.0.0.1:8000/docs while your app is running. You see a clean page that lists every route in your API. Each route shows the HTTP method, the path, and a button to expand it and test it live.

ReDoc — at /redoc

Visit http://127.0.0.1:8000/redoc for a reading-friendly, structured reference page. ReDoc is better for sharing with people who just want to read the API design without testing it.

How FastAPI Builds These Pages Automatically

Your Python Code
       |
       | FastAPI reads your:
       |   - route paths
       |   - function parameters
       |   - Pydantic models
       |   - return types
       v
  OpenAPI Schema (JSON)
  at /openapi.json
       |
       v
  Swagger UI reads this schema
  and draws the interactive page

FastAPI generates an OpenAPI schema — a standardized JSON description of your API. Swagger UI and ReDoc both read this schema and display it visually. You never write the schema by hand.

What You See on the /docs Page

Each route on the Swagger UI page shows:

• The HTTP method badge (green for GET, blue for POST, orange for PUT, red for DELETE)
• The URL path
• A short description (if you add a docstring to your function)
• An "Execute" button to send a real request

Adding Descriptions to Your Routes

Add a docstring inside your function and FastAPI shows it in the docs:

@app.get("/users")
def get_users():
    """
    Returns a list of all registered users.
    Each user has an id, name, and email.
    """
    return [{"id": 1, "name": "Priya"}]

FastAPI picks up that docstring and displays it on the /docs page. No extra configuration needed.

Adding Titles and Descriptions to the Whole App

You can add a title, description, and version number to your entire API when you create the app object:

app = FastAPI(
    title="Student Management API",
    description="Manage student records, courses, and grades.",
    version="2.1.0"
)

These details appear at the top of both /docs and /redoc.

How to Test an Endpoint in /docs

Follow these steps on the Swagger UI page:

Step 1: Click on any route (e.g., GET /users)
        ↓
Step 2: Click the "Try it out" button
        ↓
Step 3: Fill in any required parameters
        ↓
Step 4: Click "Execute"
        ↓
Step 5: See the real response below:
        - Response body (JSON)
        - HTTP status code
        - Response headers

The OpenAPI JSON — The Engine Behind the Docs

Visit http://127.0.0.1:8000/openapi.json to see the raw schema that powers the docs pages. Other tools — like API gateways, code generators, and testing tools — also read this schema to integrate with your API automatically.

Adding Tags to Group Your Routes

As your API grows, you can group routes into sections using tags:

@app.get("/users", tags=["Users"])
def get_users():
    return []

@app.get("/products", tags=["Products"])
def get_products():
    return []

The /docs page now shows two collapsible sections: one labeled Users and one labeled Products. This keeps large APIs organized and readable.

Key Points

• FastAPI auto-generates /docs (Swagger UI) and /redoc (ReDoc) for every app.
• These pages come from the OpenAPI schema at /openapi.json.
• Add docstrings to functions to show descriptions in the docs.
• Pass title, description, and version to FastAPI() for a professional header.
• Use tags on routes to group them into sections inside /docs.