Customize FastAPI Swagger UI and ReDoc

FastAPI provides automatic API documentation. It uses Swagger UI and ReDoc. These tools are powerful. But they look generic. You can customize them. This makes your API unique.

Custom branding helps developers. It creates a professional image. This guide shows you how. You will change colors, logos, and titles.

Why Customize API Documentation?

Default docs work well. But they lack personality. Custom docs improve user experience. They reinforce your brand. They make your API memorable.

You can match your company's theme. You can add helpful contact info. This is key for developer adoption. Good docs reduce support requests.

Accessing Default Documentation

First, create a basic FastAPI app. Run it and see the default docs. The Swagger UI is at /docs. The ReDoc is at /redoc.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

Run the app with Uvicorn. Visit the localhost URLs. You will see the standard interface. Now, let's change it.

Customizing Swagger UI

Use the swagger_ui_parameters argument. Pass it when creating the FastAPI app. This argument accepts a dictionary. You can set many options.

from fastapi import FastAPI

app = FastAPI(
    title="My Awesome API",
    swagger_ui_parameters={
        "deepLinking": True,
        "syntaxHighlight.theme": "monokai",
        "defaultModelsExpandDepth": 2,
        "docExpansion": "none",
    },
)

deepLinking allows direct links to operations. The syntaxHighlight theme changes code colors. defaultModelsExpandDepth controls schema display. docExpansion sets the initial panel state.

Changing Colors and Logo

You can inject custom CSS. Use the swagger_ui_init_oauth parameter. Or serve a custom CSS file. This method is more flexible.

app = FastAPI(
    swagger_ui_parameters={
        "syntaxHighlight.theme": "obsidian",
    },
)

For advanced theming, create a CSS file. Override the Swagger UI classes. Then serve it via a static file route. This gives full control.

Customizing ReDoc

ReDoc customization is similar. Use the redoc_url and related parameters. You can also use redoc_ui_parameters.

app = FastAPI(
    redoc_url="/custom-redoc",
    redoc_ui_parameters={
        "theme": {
            "colors": {
                "primary": {"main": "#ff0000"}
            }
        }
    },
)

This changes the primary color to red. It also moves the ReDoc endpoint. Now it is at /custom-redoc.

Adding a Custom Favicon and Logo

A favicon appears in the browser tab. A logo appears in the docs header. You can set them easily. Use the docs_url and redoc_url parameters.

But for full control, serve static files. Create an images directory. Place your logo and favicon there. Then mount the static files.

from fastapi.staticfiles import StaticFiles

app.mount("/static", StaticFiles(directory="static"), name="static")

Now reference them in your HTML. Or use them in your custom CSS. This completes the branded look.

Complete Customization Example

Let's build a full example. We will change the title, theme, and colors. We will also add a custom path.

from fastapi import FastAPI

app = FastAPI(
    title="Company API Portal",
    description="Internal API for data services.",
    version="2.0.0",
    docs_url="/api/docs",
    redoc_url="/api/redoc",
    swagger_ui_parameters={
        "defaultModelsExpandDepth": -1,
        "operationsSorter": "method",
        "filter": True,
        "displayRequestDuration": True,
    },
    redoc_ui_parameters={
        "hideDownloadButton": True,
        "expandResponses": "200",
    },
)

@app.get("/items/")
def read_items():
    """Fetch a list of items."""
    return [{"id": 1, "name": "Sample"}]

This configures many aspects. The docs are now at /api/docs. Operations are sorted by HTTP method. The request duration is shown. ReDoc hides the download button.

Integrating with Other FastAPI Features

Custom docs work with all FastAPI features. For example, proper FastAPI Error Handling will show in your docs. Errors appear in the schemas.

If you use FastAPI REST API Pagination, the parameters display. Your custom theme will apply to these elements too.

For apps using FastAPI Async Database with asyncpg SQLAlchemy, the docs remain fast. The UI customization does not affect performance.

Testing Your Custom Documentation

Always test your changes. Run your application. Open the custom docs URLs. Check all interactive elements.

Try the "Try it out" buttons. Ensure they work. Verify the theme looks good. Test on different browsers.

Conclusion

Customizing Swagger UI and ReDoc is simple. It adds a professional touch to your API. Use the parameters provided by FastAPI.

Change titles, colors, and logos. Serve custom CSS for deep changes. This improves the developer experience.

Your API documentation becomes a branded portal. It helps users understand and use your services. Start customizing your docs today.