Skip to main content

Customizing Interactive Documentation

You can customize the interactive documentation in this project by configuring the FastAPI application instance to change default URLs, modify UI behavior, or serve documentation assets from custom locations.

Change Documentation URLs​

To change the default paths for Swagger UI (/docs) and ReDoc (/redoc), provide the docs_url and redoc_url arguments when instantiating the FastAPI class.

from fastapi import FastAPI

# Change Swagger UI to /documentation and ReDoc to /api-docs
app = FastAPI(docs_url="/documentation", redoc_url="/api-docs")

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

Disable Interactive Documentation​

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

from fastapi import FastAPI

# Disable ReDoc but keep Swagger UI at the default /docs
app = FastAPI(redoc_url=None)

# Or disable both for production environments
# app = FastAPI(docs_url=None, redoc_url=None)

Configure Swagger UI Parameters​

You can modify the behavior of Swagger UI (such as disabling syntax highlighting or enabling deep linking) by passing a dictionary to swagger_ui_parameters. These parameters are passed directly to the Swagger UI initialization object in the browser.

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}"}

Configure OAuth2 for Swagger UI​

If your API uses OAuth2, you can pre-configure the "Authorize" button in Swagger UI using swagger_ui_init_oauth.

from fastapi import FastAPI

app = FastAPI(
    swagger_ui_init_oauth={
        "clientId": "your-client-id",
        "appName": "your-app-name",
        "usePkceWithAuthorizationCodeGrant": True
    }
)

Self-hosting Documentation Assets​

In environments without internet access, or when you need to pin specific versions of Swagger UI and ReDoc, you can disable the automatic endpoints and serve the documentation manually using custom asset URLs.

This approach uses 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,
)

# 1. Disable the automatic documentation
app = FastAPI(docs_url=None, redoc_url=None)

# 2. Create a manual route for Swagger UI
@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,
        # Use custom CDN or local static file URLs
        swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
        swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
    )

# 3. Required for OAuth2 support in manual Swagger UI
@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
    return get_swagger_ui_oauth2_redirect_html()

# 4. Create a manual route for ReDoc
@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="https://unpkg.com/redoc@2/bundles/redoc.standalone.js",
    )

Troubleshooting​

Disabling OpenAPI Schema​

If you set openapi_url=None in the FastAPI constructor, both Swagger UI and ReDoc will be automatically disabled, as they depend on the OpenAPI schema to function.

OAuth2 Redirects​

If you change docs_url or use a custom implementation, ensure that swagger_ui_oauth2_redirect_url (default: /docs/oauth2-redirect) is correctly configured. If you are serving Swagger UI manually, you must also manually add the route for the redirect as shown in the "Self-hosting" example above.