Skip to content

OpenAPI

FastAPI automatically generates an OpenAPI 3.x schema from the route declarations and Pydantic models. This schema powers the interactive documentation UI and can be exported for API clients or contract review.

Interactive docs

With the backend running locally, open either of these:

URL What it shows
http://localhost:8000/docs Swagger UI — try requests directly in the browser
http://localhost:8000/redoc ReDoc — cleaner read-only documentation
http://localhost:8000/openapi.json Raw OpenAPI JSON schema

The interactive docs let you log in, authorize with a Bearer token, and make real API calls — useful for exploring endpoints without writing curl commands.

Exporting the schema

Export from a running server:

curl -s http://localhost:8000/openapi.json > openapi.json

Export from Python without starting a server (useful in CI):

python - <<'PY'
import json
from app.main import app
print(json.dumps(app.openapi(), indent=2))
PY

Using the schema

The exported openapi.json can be used with:

  • API client generators — tools like openapi-generator or orval can generate TypeScript/Python clients from the schema
  • Postman / Insomnia — import the schema to get a full API collection
  • Contract testing — compare the schema against the frontend's API client types to catch drift

Keeping docs in sync

The OpenAPI schema is always generated from the live code — it can't get out of sync with the implementation. However, the narrative documentation in this site can drift from the actual endpoints.

If you add a new endpoint or change a route, update the Endpoint Groups page to match.