Organizing with Tags and External Docs

To organize your API operations into logical groups and provide additional context through external links, you can use tags and external documentation metadata.

Grouping Operations with Tags

You can group related path operations in the interactive documentation (Swagger UI) by using the tags parameter in your route decorators.

from fastapi import FastAPI

app = FastAPI()

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

@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

In this example, the operations are grouped under "users" and "items" headings in the /docs interface.

Adding Metadata to Tags

To provide descriptions or external links for your tags, define a list of dictionaries and pass it to the openapi_tags parameter of the FastAPI constructor. This metadata is validated against the Tag model in fastapi.openapi.models.

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"}]

@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}]

Key Metadata Fields

• name: (Required) The name of the tag. It must match the string used in the tags parameter of your routes.
• description: A short description of the tag. Supports Markdown.
• externalDocs: A dictionary containing a description and a url for additional documentation. This maps to the ExternalDocumentation model.

Providing Global External Documentation

You can add a link to external documentation for the entire API using the openapi_external_docs parameter. This is useful for linking to a general wiki, a separate developer portal, or a specification document.

from fastapi import FastAPI

external_docs = {
    "description": "External API documentation.",
    "url": "https://docs.example.com/api-general",
}

app = FastAPI(openapi_external_docs=external_docs)

This metadata is also validated using the ExternalDocumentation model, requiring a valid url.

Troubleshooting and Best Practices

Unique Tag Names

Each tag name in the openapi_tags list must be unique. If you define the same tag name twice, the behavior in the UI may be inconsistent.

Tag Ordering

The order of tags in the openapi_tags list determines the order in which they appear in the Swagger UI. Tags used in routes but not declared in openapi_tags will appear after the declared ones, usually in alphabetical order.

URL Validation

The url field in ExternalDocumentation is validated by Pydantic's AnyUrl. Ensure your URLs include the scheme (e.g., https://) to avoid validation errors during application startup.

Markdown Support

Both the description field in Tag and ExternalDocumentation support CommonMark syntax, allowing you to include bold text, links, and lists in your documentation.