OpenAPI: Customizing Swagger and Redoc

The most famous feature of FastAPI is its self-documenting nature. By simply writing your code, you get two interactive websites:

1. Swagger UI (/docs): Great for testing.
2. Redoc (/redoc): Great for reading.

In this lesson, we learn how to take those docs from "Basic" to "Professional."

---

1. Global Metadata

You should define your API's "Brand" when you initialize the FastAPI class. This includes the title, version, and licensing information.

app = FastAPI(
    title="ShShell Payments API",
    description="A secure, production-grade API for processing micro-transactions.",
    version="2.1.0",
    terms_of_service="https://shshell.com/terms/",
    contact={
        "name": "API Support",
        "url": "https://shshell.com/support",
        "email": "dev@shshell.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
)

---

2. Using Tags for Organization

As your API grows, having 50 endpoints in one long list is overwhelming. Use Tags to group them logically (e.g., "Users", "Billing", "Reports").

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

@app.post("/billing/invoice", tags=["Billing"])
async def create_invoice():
    return {}

---

3. Explaining Status Codes and Responses

You can document exactly what an error looks like so that Frontend developers know how to handle them.

@app.get(
    "/items/{id}",
    responses={
        200: {"description": "Item found and returned"},
        404: {"description": "Item not found in our database"},
        403: {"description": "You do not have permission to view this item"},
    }
)
async def read_item(id: str):
    ...

---

4. Declaring Operation IDs

If you are generating client code (like a TypeScript SDK) from your OpenAPI schema, the function names are often derived from your Python function names. You can override this using operation_id.

@app.get("/items/", operation_id="listAllInventoryItems")
async def read_items():
    ...

---

Visualizing the Documentation Ecosystem

graph TD
    A["FastAPI Code"] --> B["OpenAPI JSON Schema (/openapi.json)"]
    B --> C["Swagger UI (/docs)"]
    B --> D["Redoc (/redoc)"]
    B --> E["Client Generators (TS/Python/Go SDKs)"]
    B --> F["Testing Tools (Postman/Insomnia)"]

---

Summary

• title and description: Set the first impression of your API.
• tags: Group endpoints for better navigation.
• responses: Document all possible failure modes.
• OpenAPI: Remember that the documentation is just a visualization of a standard JSON schema.

In the next lesson, we’ll look at JSON Schema and Examples, ensuring the data payloads are as clear as the route titles.

---

Exercise: The Professional Tag

You want your "Billing" endpoints to appear at the very top of the Swagger UI with a specific description: "Financial operations and invoice management." How do you define this in the FastAPI initialization using openapi_tags?