Metadata and Docs URLs

Warning

The current page still doesn’t have a translation for this language.

But you can help translating it: Contributing.

You can customize several metadata configurations in your FastAPI application.

Title, description, and version

You can set the:

• Title: used as your API’s title/name, in OpenAPI and the automatic API docs UIs.
• Description: the description of your API, in OpenAPI and the automatic API docs UIs.
• Version: the version of your API, e.g. v2 or 2.5.0.
  • Useful for example if you had a previous version of the application, also using OpenAPI.

To set them, use the parameters title, description, and version:

from fastapi import FastAPI
app = FastAPI(
    title="My Super Project",
    description="This is a very fancy project, with auto docs for the API and everything",
    version="2.5.0",
)
@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

With this configuration, the automatic API docs would look like:

Metadata for tags

You can also add additional metadata for the different tags used to group your path operations with the parameter openapi_tags.

It takes a list containing one dictionary for each tag.

Each dictionary can contain:

• name (required): a str with the same tag name you use in the tags parameter in your path operations and APIRouters.
• description: a str with a short description for the tag. It can have Markdown and will be shown in the docs UI.
• externalDocs: a dict describing external documentation with:
  • description: a str with a short description for the external docs.
  • url (required): a str with the URL for the external documentation.

Create metadata for tags

Let’s try that in an example with tags for users and items.

Create metadata for your tags and pass it to the openapi_tags parameter:

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"}]
@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

Notice that you can use Markdown inside of the descriptions, for example “login” will be shown in bold (login) and “fancy” will be shown in italics (fancy).

Tip

You don’t have to add metadata for all the tags that you use.

Use your tags

Use the tags parameter with your path operations (and APIRouters) to assign them to different tags:

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"}]
@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

Info

Read more about tags in Path Operation Configuration.

Check the docs

Now, if you check the docs, they will show all the additional metadata:

Order of tags

The order of each tag metadata dictionary also defines the order shown in the docs UI.

For example, even though users would go after items in alphabetical order, it is shown before them, because we added their metadata as the first dictionary in the list.

OpenAPI URL

By default, the OpenAPI schema is served at /openapi.json.

But you can configure it with the parameter openapi_url.

For example, to set it to be served at /api/v1/openapi.json:

from fastapi import FastAPI
app = FastAPI(openapi_url="/api/v1/openapi.json")
@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

If you want to disable the OpenAPI schema completely you can set openapi_url=None, that will also disable the documentation user interfaces that use it.

Docs URLs

You can configure the two documentation user interfaces included:

• Swagger UI: served at /docs.
  • You can set its URL with the parameter docs_url.
  • You can disable it by setting docs_url=None.
• ReDoc: served at /redoc.
  • You can set its URL with the parameter redoc_url.
  • You can disable it by setting redoc_url=None.

For example, to set Swagger UI to be served at /documentation and disable ReDoc:

from fastapi import FastAPI
app = FastAPI(docs_url="/documentation", redoc_url=None)
@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]