skip to content

In FastAPI, where do the title, tag groups, summaries and descriptions shown on the /docs page come from?

level: juniorimportance: should knowfreq 40%

answer

  1. both UIs render one JSON document
  2. constructor arguments on the app
  3. decorator keywords per path operation
  4. function name and docstring as defaults

basics

~10 s

From FastAPI's generated OpenAPI schema: FastAPI(title, version, description, openapi_tags) sets the API-level text, and each decorator's tags, summary, description, response_description and deprecated set an operation's, defaulting to the function name and docstring.

solid answer

~30 s

Swagger UI at `/docs` and ReDoc at `/redoc` only render `/openapi.json`, so everything they show is what FastAPI put into that schema. API-level text comes from `FastAPI(title=..., version=..., summary=..., description=..., openapi_tags=[...])`; `description` accepts Markdown, and the order of `openapi_tags` is the order of the groups. Per operation, `tags=["items"]` groups it, `summary` defaults to the function name title-cased (`read_item` becomes "Read Item"), `description` defaults to the docstring cut at the first `\f`, and `response_description` defaults to "Successful Response". `deprecated=True` flags an operation without removing it, and `include_in_schema=False` leaves it out of the schema while the route keeps answering.

code

python · 42 lines
python
from enum import Enum

from fastapi import FastAPI


class Tags(Enum):
    items = "items"


app = FastAPI(
    title="Shop API",
    version="2.5.0",
    description="Catalogue and orders. **Markdown** works here.",
    openapi_tags=[{"name": "items", "description": "Browse the catalogue."}],
)


@app.get("/items/{item_id}", tags=[Tags.items], response_description="The item")
def read_item(item_id: int):
    """Return one item by its numeric id.

    Shown in /docs as the operation's description.
    \f
    Internal note: kept out of the schema.
    """
    return {"id": item_id}


@app.get("/legacy-items", tags=[Tags.items], deprecated=True)
def list_legacy_items():
    return []


@app.get("/healthz", include_in_schema=False)
def healthz():
    return {"ok": True}


op = app.openapi()["paths"]["/items/{item_id}"]["get"]
print(op["summary"])       # Read Item
print(op["description"])   # docstring up to the form feed
print(sorted(app.openapi()["paths"]))  # /healthz is absent

go deeper

for a junior

Recall the split: API-level text goes on FastAPI(), operation text on the decorator, with the function name and docstring filling the gaps.

for a middle

Explain that both UIs only render /openapi.json, list the defaults FastAPI fills in, and show the form-feed trick for keeping notes out of the schema.

for a senior

Treat summaries, tags and descriptions as part of the published API surface: one tag per router, deprecations flagged well before removal, internal routes kept out of the schema.

for a principal

Decide what the schema may say publicly, who reviews docstring changes that ship to readers, and how deprecation flags tie into the team's removal policy.

## What the docs page actually renders FastAPI ships two documentation UIs: **Swagger UI** at `/docs` and **ReDoc** at `/redoc`. Neither reads your Python code. Each is a small HTML page that fetches the JSON document FastAPI serves at `/openapi.json` and draws it. So every title, group and sentence on those pages comes from the **OpenAPI schema** FastAPI generated, and FastAPI builds that schema from two places: the arguments you gave the `FastAPI` application object, and the arguments and defaults of every **path operation** (a function bound to a method and path with a decorator such as `@app.get`). ## API-level metadata on the FastAPI constructor | Argument | Default | What it controls | |---|---|---| | `title` | `"FastAPI"` | the heading of the docs page | | `version` | `"0.1.0"` | your API's own version, not the OpenAPI version | | `summary` | none | a one-line summary under the title | | `description` | none | longer text, rendered as Markdown | | `openapi_tags` | none | descriptions and order of the tag groups | | `terms_of_service`, `contact`, `license_info` | none | the legal and contact block | - `title` and `version` must not be empty while the schema is enabled: FastAPI asserts both when the app is created. - `openapi_tags` is a list of dicts, each with a required `name` and an optional `description` (Markdown) and `externalDocs`. The order of the list is the order of the groups on the page, and you do not have to describe every tag you use. ## Per-operation metadata on the decorator These are keyword arguments to the **decorator**, not parameters of the function: - `tags=["items"]` puts the operation in a group. Tags may also be `Enum` members, which keeps spelling consistent in a large app. - `summary="..."` is the operation's one-line title. - `description="..."` is the long text. Leave it out and FastAPI uses the function's **docstring**, Markdown included. - `response_description` describes the main response. - `deprecated=True` marks the operation as deprecated in the schema, so the UIs flag it, while it keeps working. - `include_in_schema=False` removes the operation from the schema and the docs; the route still answers requests. ## The defaults FastAPI fills in When you set nothing, FastAPI still produces readable docs: 1. **Summary**: the function name with underscores turned into spaces and title-cased, so `read_item` shows as "Read Item". 2. **Description**: the docstring, with its indentation cleaned up and cut at the first form-feed character `\f`. Text after `\f` stays in the source for other documentation tools and never reaches the schema. 3. **Response description**: "Successful Response" for the main status code. 4. **Validation error**: a `422` response described as "Validation Error" is added to any operation that takes parameters or a body. ```python @app.get("/items/{item_id}", tags=["items"]) def read_item(item_id: int): """Return one item. \f Internal: cache is warmed by the nightly job. """ ``` ## Tags from routers `APIRouter(prefix="/items", tags=["items"])`, or `app.include_router(router, tags=["items"])`, applies a tag to every operation in that router, added to whatever tags an operation declares itself. Teams usually give each router one tag so that the docs mirror the code layout, and client generators that group methods by tag mirror it too. ## Checking what you published Because the UIs are only renderers, the quickest way to answer "why does the page say this?" is to read the schema itself: - `info` holds `title`, `version`, `summary` and `description` from the constructor. - The top-level `tags` array holds your `openapi_tags`, in your order. - Each operation under `paths` holds its `tags`, `summary`, `description`, `operationId` and `deprecated` flag. - In a test, `app.openapi()` returns the same dict, so a team can assert that every operation has a tag, or that no internal note leaked out of a docstring. Behaviour that lives only in the UI, such as how Swagger UI expands its sections, is not part of the schema; it is set separately through `swagger_ui_parameters` on `FastAPI()`. ## Where the rest of the text comes from Field-level text, such as a field's `description` or `examples`, comes from the Pydantic models used as bodies and responses; that is covered with Pydantic's schema customisation. Security schemes appear because a path operation depends on one of FastAPI's security classes. Everything else on the page is one of the settings above, which is why fixing a confusing docs page almost always means editing a decorator, a docstring or the `FastAPI()` call rather than the UI.

  • In FastAPI, how do you keep developer notes in a path operation's docstring without publishing them in /docs?
    Put a form-feed escape `\f` in the docstring. FastAPI cuts the description at the first `\f`, so everything after it stays in the source for other documentation tools but never reaches the OpenAPI schema. Passing `description=` to the decorator replaces the docstring entirely.
  • In FastAPI, what is the difference between deprecated=True and include_in_schema=False on a path operation?
    `deprecated=True` keeps the operation in the schema, flagged as deprecated, so readers and generated clients can see it is going away. `include_in_schema=False` drops it from the schema and the docs. Neither disables the route: both still answer requests.

  • The docs page reads the Python source code directly to build its text.
  • FastAPI's version argument sets the OpenAPI specification version.
  • Setting include_in_schema=False disables the endpoint entirely.
  • Without a summary, the docs show the URL path as the operation title.
  • Every tag must be described in openapi_tags before an operation can use it.