Skip to main content

Configuring Application Metadata

To configure the metadata for your API, such as the title, version, and description, you pass specific parameters to the FastAPI application constructor. This metadata is automatically included in the generated OpenAPI schema and displayed in the interactive documentation (Swagger UI and ReDoc).

Setting Basic API Metadata​

You can define the primary identity of your API using the title, summary, description, and version parameters. The description parameter supports Markdown.

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",
    summary="Deadpool's favorite app. Nuff said.",
    description=description,
    version="0.0.1",
)
  • title: The name of your API.
  • summary: A short overview (available in OpenAPI 3.1.0+).
  • description: A detailed explanation. Using triple-quoted strings allows for multi-line Markdown.
  • version: The version of your specific application (e.g., "2.5.0"), not the version of FastAPI or OpenAPI.

Adding Contact and License Information​

For production APIs, you can include contact details and licensing information using dictionaries.

from fastapi import FastAPI

app = FastAPI(
    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",
    },
)
  • contact: Can contain name, url, and email.
  • license_info: Requires a name. You can also provide a url or an SPDX identifier (e.g., "MIT"), but these two are mutually exclusive.

Organizing and Describing Tags​

You can provide additional metadata for the tags used in your path operations by passing a list of dictionaries to openapi_tags. This allows you to add descriptions and external documentation links to groups of endpoints in the UI.

from fastapi import FastAPI

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"}, {"name": "Ron"}]

Customizing Documentation Endpoints​

By default, FastAPI serves the OpenAPI schema at /openapi.json, Swagger UI at /docs, and ReDoc at /redoc. You can change these paths or disable them entirely.

from fastapi import FastAPI

app = FastAPI(
    openapi_url="/api/v1/openapi.json",
    docs_url="/documentation",
    redoc_url=None,
)
  • openapi_url: The path to the raw JSON schema. Setting this to None disables all documentation interfaces.
  • docs_url: The path for Swagger UI. Set to None to disable.
  • redoc_url: The path for ReDoc. Set to None to disable.

Troubleshooting and Gotchas​

License Requirements​

If you provide the license_info dictionary, the name field is required. If you use an SPDX identifier, do not provide a URL:

# Correct use of SPDX identifier
app = FastAPI(
    license_info={
        "name": "MIT",
        "identifier": "MIT",
    }
)

Disabling Documentation​

If you set openapi_url=None, both /docs and /redoc will be automatically disabled, even if you have provided paths for docs_url or redoc_url.

Markdown Rendering​

If your Markdown descriptions are not rendering correctly in Swagger UI, ensure you are using standard CommonMark syntax. Triple-quoted strings in Python are the recommended way to maintain formatting for multi-line descriptions.