Saurabh Chodvadiya's blog

Elevating Your API Documentation: Customizing Swagger UI in FastAPI

Saurabh Chodvadiya's photo
Saurabh Chodvadiya
·

3 min read

Introduction:

Swagger UI is an essential tool for interactive API documentation, and FastAPI makes it seamless to integrate Swagger UI with your API out of the box. While the default Swagger UI is impressive, customization allows you to align the documentation with your branding and specific needs. In this blog, we’ll explore various customization options in FastAPI to enhance Swagger UI, including adding buttons, changing names, and applying unique styles. Let’s dive into the art of crafting a custom Swagger UI with Python code.

Step 1: Setting Up a FastAPI Application

Before we begin customizing the Swagger UI, let’s set up a basic FastAPI application as a starting point.

# main.py
from fastapi import FastAPI

app = FastAPI()

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

Step 2: Customizing Swagger UI with Python Code

FastAPI provides a straightforward way to customize Swagger UI using the swagger_ui_html function. By overriding this function, we can inject our desired changes to the Swagger UI HTML template.

# main.py
from fastapi import FastAPI, Response
from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.openapi.models import SwaggerUIResponse

app = FastAPI()

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

# Custom Swagger UI HTML template
def custom_swagger_ui_html(*args, **kwargs):
    html = get_swagger_ui_html(*args, **kwargs)
    # Customize the HTML here
    # For example, adding a custom button
    custom_button = '<a href="https://example.com/docs" target="_blank" class="my-custom-button">Custom Docs</a>'
    html = html.replace('</head>', '<style>.my-custom-button { color: #fff; background-color: #007BFF; padding: 10px 20px; border-radius: 5px; text-decoration: none; }</style></head>')
    html = html.replace('</head>', custom_button + '</head>')
    return Response(content=html, media_type="text/html")

app.openapi = custom_swagger_ui_html

Step 3: Explore the Custom Swagger UI

With the customization code in place, it’s time to run the FastAPI application using uvicorn:

uvicorn main:app --reload

Step 4: Add More Customizations

You can further customize Swagger UI to your liking. Here are some additional examples:

  1. Change Page Title:

You can change the page title by modifying the custom_swagger_ui_html function.

html = html.replace('<title>Swagger UI</title>', '<title>My Custom API Documentation</title>')

2. Add a Custom Header:

Include a custom header to display additional information.

custom_header = '<div class="my-custom-header">Welcome to My Custom API</div>'
html = html.replace('</head>', '<style>.my-custom-header { font-size: 24px; color: #333; }</style></head>')
html = html.replace('</head>', custom_header + '</head>')

3. Change Logo:

Replace the default Swagger UI logo with your brand’s logo.

custom_logo = '<img src="/path/to/your/logo.png" alt="My Custom Logo" class="my-custom-logo">'
html = html.replace('</head>', '<style>.my-custom-logo { max-width: 100px; }</style></head>')
html = html.replace('<div id="swagger-ui"></div>', custom_logo + '<div id="swagger-ui"></div>')

Step 5: Save and Explore Your Custom Swagger UI

Save the changes and navigate to http://127.0.0.1:8000/docs in your web browser to explore the customized Swagger UI. Feel free to experiment with additional customizations to tailor the documentation to your specific requirements.

Conclusion:

Congratulations! You have successfully customized Swagger UI in FastAPI using Python code. By leveraging the swagger_ui_html function, you can add buttons, change names, apply styles, and tailor the Swagger UI to match your API's unique identity. FastAPI's flexibility empowers you to deliver a customized and engaging user experience for API documentation.

As you explore further, you’ll discover countless possibilities to elevate your API’s documentation and showcase your API with finesse. Customizing Swagger UI not only enhances usability but also reflects your brand’s identity, making the documentation a seamless extension of your application. Happy coding and customizing!

FastAPIswagger-uiswaggercusomize swagger