Introduction

As developers, we often focus on writing code and building features, sometimes overlooking the importance of documentation. However, well-documented APIs are crucial for both internal teams and external developers who consume our services. In this blog post, we'll explore how to leverage Swagger UI and ReDoc to create stunning API documentation for your FastAPI applications.

Why API Documentation Matters

Before diving into the technical details, let's briefly discuss why API documentation is essential:

1. Ease of use: Clear documentation helps developers understand and integrate your API quickly.
2. Reduced support overhead: Well-documented APIs lead to fewer support requests and questions.
3. Improved collaboration: Documentation serves as a shared reference for teams working on the same project.
4. Faster onboarding: New team members can get up to speed more quickly with comprehensive documentation.

Introducing Swagger UI and ReDoc

FastAPI comes with built-in support for two popular API documentation tools: Swagger UI and ReDoc. Both tools generate interactive documentation based on the OpenAPI (formerly known as Swagger) specification.

Swagger UI

Swagger UI provides a user-friendly interface for exploring and testing API endpoints. It allows users to:

• View all available endpoints and their descriptions
• Try out API calls directly from the browser
• Understand request and response schemas

ReDoc

ReDoc is another documentation generator that offers a clean, responsive interface for API documentation. It focuses on readability and aesthetics, making it an excellent choice for public-facing API documentation.

Setting Up Swagger UI and ReDoc in FastAPI

FastAPI makes it incredibly easy to set up both Swagger UI and ReDoc. Let's walk through the process step by step.

Step 1: Create a FastAPI Application

First, let's create a simple FastAPI application:

from fastapi import FastAPI

app = FastAPI(
    title="My Awesome API",
    description="This is a sample API for demonstrating Swagger UI and ReDoc",
    version="1.0.0"
)

@app.get("/")
async def root():
    return {"message": "Hello, World!"}

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Step 2: Configure Documentation URLs

By default, FastAPI sets up Swagger UI at /docs and ReDoc at /redoc. You can customize these URLs if needed:

app = FastAPI(
    title="My Awesome API",
    description="This is a sample API for demonstrating Swagger UI and ReDoc",
    version="1.0.0",
    docs_url="/swagger",

# Custom Swagger UI URL
    redoc_url="/api-docs"

# Custom ReDoc URL
)

Step 3: Add Metadata and Descriptions

To make your documentation more informative, add metadata and descriptions to your API endpoints:

from fastapi import FastAPI, Path, Query

app = FastAPI(
    title="My Awesome API",
    description="This is a sample API for demonstrating Swagger UI and ReDoc",
    version="1.0.0"
)

@app.get(
    "/items/{item_id}",
    summary="Read a specific item",
    description="This endpoint retrieves information about a specific item based on its ID."
)
async def read_item(
    item_id: int = Path(..., description="The ID of the item to retrieve"),
    q: str = Query(None, description="An optional query parameter")
):
    return {"item_id": item_id, "q": q}

Step 4: Document Request and Response Models

Use Pydantic models to define and document request and response schemas:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    return item

Best Practices for API Documentation

To make the most of Swagger UI and ReDoc, follow these best practices:

1. Use clear and concise descriptions for endpoints, parameters, and models.
2. Provide examples for request bodies and responses.
3. Group related endpoints using tags.
4. Use appropriate HTTP status codes and document error responses.
5. Keep your documentation up-to-date as your API evolves.

Advanced Features

Both Swagger UI and ReDoc offer advanced features to enhance your API documentation:

Authentication

Document authentication methods using FastAPI's security utilities:

from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.get("/secure-endpoint")
async def secure_endpoint(token: str = Depends(oauth2_scheme)):
    return {"message": "This is a secure endpoint"}

Custom OpenAPI Schema

Customize the OpenAPI schema to add additional information or modify the default behavior:

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        description="This is a custom OpenAPI schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

Conclusion

By leveraging Swagger UI and ReDoc in your FastAPI applications, you can create comprehensive, interactive API documentation that enhances the developer experience and promotes the adoption of your API. Remember to keep your documentation clear, concise, and up-to-date to maximize its effectiveness.