OpenAPI Schema and Docs

Every FastAPI app publishes an OpenAPI 3 schema describing all routes, parameters, request bodies, and response models, plus two interactive UIs: Swagger UI at /docs and ReDoc at /redoc. The schema is generated from your code, so documentation never drifts from the implementation.

The Document Endpoints

• /openapi.json - the machine-readable schema; feed it to code generators and API clients.
• /docs - Swagger UI: explore, "Try it out", and copy cURL commands.
• /redoc - ReDoc: a cleaner reference layout for larger APIs.

curl http://127.0.0.1:8000/openapi.json | python3 -m json.tool | head -40

Customizing the Metadata

from fastapi import FastAPI

app = FastAPI(
    title="Shop API",
    version="1.4.0",
    description="Product and order endpoints for the shop.",
    openapi_url="/api/openapi.json",
    docs_url="/api/docs",
    redoc_url="/api/redoc",
    contact={"name": "API Team", "email": "[email protected]"},
    license_info={"name": "MIT"},
)

Moving the URLs lets you keep the UIs out of the way or behind auth.

Disabling or Protecting Docs

app = FastAPI(docs_url=None, redoc_url=None)  # no UIs at all

For production, a common pattern is a mount that requires a header or IP allowlist, or simply serving the UIs only on internal networks while /openapi.json stays public for client generators.

Generating Clients from the Schema

# with openapi-generator
openapi-generator-cli generate \
  -i openapi.json -g typescript-fetch -o client-ts

Because the schema is derived from typed code, generated clients match your API exactly - the contract test of having a contract.

Summary

FastAPI ships OpenAPI for free: /openapi.json for machines, /docs and /redoc for humans, all generated from your signatures and models. Customize title, version, and URLs in the FastAPI constructor, disable the UIs in production when appropriate, and use the schema to generate type-safe API clients.