Skip to main content

Configuring Application Metadata

When you create a FastAPI application, the interactive documentation (available at /docs or /redoc) uses default values like "FastAPI" for the title and "0.1.0" for the version. You can customize this metadata to provide a professional identity for your API.

Configure Basic API Information​

You can set the title, summary, version, and other metadata directly in the FastAPI class constructor.

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
)

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

Key Metadata Parameters​

  • title: The name of your API displayed at the top of the documentation.
  • summary: A short, one-line explanation of the API.
  • description: A detailed explanation. This field supports Markdown (CommonMark), allowing you to include headers, lists, and links.
  • version: The version of your specific application (not the FastAPI version).
  • terms_of_service: A URL pointing to the terms of service for your API.

Define Contact and License Information​

The contact and license_info parameters accept dictionaries to provide legal and support details.

Contact Information​

The contact dictionary can contain:

  • name: The person or organization name.
  • url: A URL for contact information.
  • email: A support email address.

License Information​

The license_info dictionary requires a name. For the link, you can provide either a url or an identifier (SPDX license expression).

Using a URL:

app = FastAPI(
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    }
)

Using an SPDX Identifier (OpenAPI 3.1.0+): The identifier field is mutually exclusive with the url field.

app = FastAPI(
    license_info={
        "name": "Apache 2.0",
        "identifier": "Apache-2.0",
    }
)

Organize Documentation with Tags​

You can group related operations and control their order in the UI using openapi_tags. This is useful for large APIs where you want to provide descriptions for the categories shown in Swagger UI.

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)

@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}]

Add External Documentation​

If you have a separate site for detailed documentation, use openapi_external_docs to link to it from the main API page.

app = FastAPI(
    openapi_external_docs={
        "description": "Detailed API Reference",
        "url": "https://example.com/api-docs",
    }
)

Troubleshooting​

Disabling Documentation​

If you set openapi_url=None, the OpenAPI schema generation is disabled, which also automatically disables the /docs (Swagger UI) and /redoc (ReDoc) endpoints.

app = FastAPI(openapi_url=None)

Overriding OpenAPI Version​

FastAPI generates OpenAPI 3.1.0 by default. If you use tools that only support older versions (like 3.0.x), you can manually override the version string. This is an attribute on the instance and cannot be set in the constructor.

app = FastAPI()
app.openapi_version = "3.0.2"

Missing Title or Version​

If you provide an openapi_url but leave title or version as empty strings, FastAPI will raise an AssertionError during initialization, as these are required by the OpenAPI specification.