Skip to main content

Managing Documentation Endpoints

FastAPI automatically generates interactive API documentation using Swagger UI and ReDoc. You can customize the URLs for these endpoints, configure the UI behavior, or disable them entirely for production environments.

Configuring Documentation URLs​

You can change the paths for the documentation and the OpenAPI schema by passing parameters to the FastAPI class constructor.

from fastapi import FastAPI

app = FastAPI(
    title="Custom Docs Path",
    openapi_url="/api/v1/openapi.json",
    docs_url="/documentation",
    redoc_url="/redocumentation",
)

@app.get("/items/")
async def read_items():
    return [{"item_id": "Foo"}]

In this example:

  • The OpenAPI JSON schema is served at /api/v1/openapi.json.
  • Swagger UI is served at /documentation.
  • ReDoc is served at /redocumentation.

Disabling Documentation​

To disable one or both of the documentation interfaces, set their respective parameters to None.

from fastapi import FastAPI

# Disable ReDoc but keep Swagger UI
app = FastAPI(redoc_url=None)

To disable all documentation and the OpenAPI schema entirely:

from fastapi import FastAPI

# Disabling openapi_url also disables docs_url and redoc_url
app = FastAPI(openapi_url=None)

Configuring Swagger UI Parameters​

FastAPI allows you to configure Swagger UI behavior using the swagger_ui_parameters argument. This accepts a dictionary of settings that are passed directly to Swagger UI.

from fastapi import FastAPI

app = FastAPI(
    swagger_ui_parameters={
        "syntaxHighlight": False, 
        "deepLinking": True,
        "defaultModelsExpandDepth": -1
    }
)

@app.get("/users/{username}")
async def read_user(username: str):
    return {"message": f"Hello {username}"}

Common parameters include:

  • syntaxHighlight: Enable or disable code highlighting in the UI.
  • deepLinking: Allow linking directly to specific operations.
  • persistAuthorization: Keep authorization data (like tokens) after a page refresh.

Self-Hosting Static Assets​

By default, FastAPI loads the JavaScript and CSS for Swagger UI and ReDoc from a CDN. If you need to run your application offline or want to host these assets yourself, you can disable the default endpoints and create custom ones using get_swagger_ui_html and get_redoc_html from fastapi.openapi.docs.

from fastapi import FastAPI
from fastapi.openapi.docs import (
    get_redoc_html,
    get_swagger_ui_html,
    get_swagger_ui_oauth2_redirect_html,
)
from fastapi.staticfiles import StaticFiles

app = FastAPI(docs_url=None, redoc_url=None)

# Mount a directory containing your local 'swagger-ui-bundle.js', etc.
# app.mount("/static", StaticFiles(directory="static"), name="static")

@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="/static/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui.css",
    )

@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
    return get_swagger_ui_oauth2_redirect_html()

@app.get("/redoc", include_in_schema=False)
async def redoc_html():
    return get_redoc_html(
        openapi_url=app.openapi_url,
        title=app.title + " - ReDoc",
        redoc_js_url="/static/redoc.standalone.js",
    )

Troubleshooting and Gotchas​

Documentation Behind Proxies​

If your FastAPI application is running behind a proxy (like Nginx or Traefik) with a path prefix (e.g., https://example.com/api/v1/), the documentation UI might fail to find the /openapi.json file.

Use the root_path parameter to ensure the UI correctly prefixes its requests:

app = FastAPI(root_path="/api/v1")

Dependency on OpenAPI URL​

The docs_url and redoc_url endpoints depend on openapi_url. If you set openapi_url=None, both documentation interfaces will be automatically disabled, even if you provided paths for them.

OAuth2 Redirects​

If you use OAuth2 authentication within Swagger UI, ensure swagger_ui_oauth2_redirect_url is correctly configured. By default, it is /docs/oauth2-redirect. If you change docs_url, you may want to update this to match your new documentation structure.