TopolearnYou get accurate, always up-to-date documentation and a test console for free, for you, your front end team and API clients.
FastAPI builds an OpenAPI description of your API from the path operations, parameters, models and type hints you declare. OpenAPI is the standard JSON format for describing HTTP APIs, and three URLs expose it out of the box:
/docs: Swagger UI, an interactive page where you expand an operation, fill in its parameters and press "Try it out" to send a real request./redoc: ReDoc, a clean read-only reference./openapi.json: the raw schema the two pages are built from.
Because the docs are generated from the same declarations FastAPI uses to validate requests, they can't drift out of date: add a query parameter or change a model field and the docs change on the next reload.
The schema is useful beyond the browser. Generators such as openapi-generator or openapi-ts produce typed client SDKs (TypeScript, Kotlin, Swift and more) from /openapi.json, and teams diff it between releases to catch breaking changes.
Enrich it cheaply as you go:
- pass
title,versionanddescription(Markdown allowed) toFastAPI(...), - group operations with
tags=[...], - write docstrings, or pass
summaryanddescriptionto the decorator, - describe model fields; their descriptions and examples appear in the schema.
To move or remove the pages, pass docs_url, redoc_url or openapi_url to FastAPI(); None disables one. openapi_url=None disables all three, since the UIs load the schema from it. Some teams switch the docs off in production, but hiding them isn't security: protect endpoints with real authentication.
Example
from fastapi import FastAPI
from fastapi.testclient import TestClient
app = FastAPI(
title="Inventory API",
version="1.2.0",
description="Manage **items** in the warehouse.",
)
@app.get("/items", tags=["items"], summary="List items")
def list_items():
"""Returns all items, newest first."""
return []
schema = TestClient(app).get("/openapi.json").json()
print(schema["info"]["title"]) # Inventory API
print(list(schema["paths"])) # ['/items']
print(schema["paths"]["/items"]["get"]["description"])
# Returns all items, newest first.
# With `fastapi dev` running, open http://127.0.0.1:8000/docs and /redocRemember
- /docs (Swagger UI), /redoc (ReDoc) and /openapi.json come for free
- Docs are generated from the same declarations used for validation, so they stay accurate
- Titles, tags, summaries, docstrings and field descriptions all flow into the schema
- docs_url, redoc_url and openapi_url move or disable the pages
Watch out for
- Treating disabled docs as protection: the endpoints are still reachable without auth.