Server Configuration

When you deploy your FastAPI application across multiple environments like staging and production, you can define these base URLs in your OpenAPI schema so that tools like Swagger UI allow you to switch between them. The servers parameter in the FastAPI constructor enables this configuration.

Define Multiple Environments

To specify multiple base URLs, pass a list of dictionaries to the servers parameter. Each dictionary is validated against the Server model defined in fastapi.openapi.models.

from fastapi import FastAPI

app = FastAPI(
    servers=[
        {"url": "https://stag.example.com", "description": "Staging environment"},
        {"url": "https://prod.example.com", "description": "Production environment"},
    ]
)

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

In this example, Swagger UI will show a dropdown menu allowing users to select which server to send requests to.

Use Server Variables

You can define dynamic URLs using placeholders in curly braces {}. These placeholders must be defined in the variables dictionary of the server entry using the ServerVariable model.

from fastapi import FastAPI

app = FastAPI(
    servers=[
        {
            "url": "https://{tenant}.example.com/api/v1",
            "description": "Multi-tenant environment",
            "variables": {
                "tenant": {
                    "default": "www",
                    "enum": ["www", "dev", "test"],
                    "description": "The tenant subdomain",
                }
            },
        }
    ]
)

The ServerVariable class (from fastapi.openapi.models) supports the following fields:

default: The default value to use for the variable.
enum: An optional list of allowed string values.
description: An optional description of the variable.

Relative URLs

FastAPI supports relative URLs in the servers configuration. This is useful when the API is served from the same host as the documentation.

from fastapi import FastAPI

app = FastAPI(
    servers=[
        {"url": "/", "description": "Default, relative server"},
        {"url": "https://prod.example.com", "description": "Production server"},
    ]
)

Control Automatic Server Generation

By default, if you provide a root_path (for example, when running behind a proxy), FastAPI automatically adds a server entry to your OpenAPI schema using that path. You can disable this behavior using the root_path_in_servers parameter.

from fastapi import FastAPI

app = FastAPI(
    root_path="/api/v1",
    root_path_in_servers=False,
    servers=[
        {"url": "https://example.com/api/v1", "description": "Hardcoded production URL"}
    ]
)

Setting root_path_in_servers=False ensures that only the servers you explicitly define in the servers list appear in the documentation, preventing FastAPI from adding the relative root_path automatically.

Troubleshooting

Swagger UI Requests Wrong URL

If your Swagger UI is making requests to the wrong base URL (e.g., missing a prefix like /api/v1), ensure that:

You have configured root_path correctly if you are behind a proxy.
If you have manually defined servers, ensure the url includes the necessary path prefixes.
If you are using relative URLs like {"url": "/"}, ensure the browser's current location matches where the API is actually hosted.

Variable Validation

OpenAPI server variables are used by the UI to construct the request URL. FastAPI does not automatically validate that the incoming request matches one of the enum values defined in ServerVariable. If you need to enforce these values at runtime, you should use standard FastAPI dependencies or path parameters.

Define Multiple Environments​

Use Server Variables​

Relative URLs​

Control Automatic Server Generation​

Troubleshooting​

Swagger UI Requests Wrong URL​

Variable Validation​