Path Operation Advanced Configuration

Warning

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

But you can help translating it: Contributing.

OpenAPI operationId

Warning

If you are not an “expert” in OpenAPI, you probably don’t need this.

You can set the OpenAPI operationId to be used in your path operation with the parameter operation_id.

You would have to make sure that it is unique for each operation.

from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", operation_id="some_specific_id_you_define")
async def read_items():
    return [{"item_id": "Foo"}]

Using the path operation function name as the operationId

If you want to use your APIs’ function names as operationIds, you can iterate over all of them and override each path operation’s operation_id using their APIRoute.name.

You should do it after adding all your path operations.

from fastapi import FastAPI
from fastapi.routing import APIRoute
app = FastAPI()
@app.get("/items/")
async def read_items():
    return [{"item_id": "Foo"}]
def use_route_names_as_operation_ids(app: FastAPI) -> None:
    """
    Simplify operation IDs so that generated API clients have simpler function
    names.
    Should be called only after all routes have been added.
    """
    for route in app.routes:
        if isinstance(route, APIRoute):
            route.operation_id = route.name  # in this case, 'read_items'
use_route_names_as_operation_ids(app)

Tip

If you manually call app.openapi(), you should update the operationIds before that.

Warning

If you do this, you have to make sure each one of your path operation functions has a unique name.

Even if they are in different modules (Python files).

Exclude from OpenAPI

To exclude a path operation from the generated OpenAPI schema (and thus, from the automatic documentation systems), use the parameter include_in_schema and set it to False;

from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", include_in_schema=False)
async def read_items():
    return [{"item_id": "Foo"}]

Advanced description from docstring

You can limit the lines used from the docstring of a path operation function for OpenAPI.

Adding an \f (an escaped “form feed” character) causes FastAPI to truncate the output used for OpenAPI at this point.

It won’t show up in the documentation, but other tools (such as Sphinx) will be able to use the rest.

from typing import Optional, Set
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None
    tags: Set[str] = []
@app.post("/items/", response_model=Item, summary="Create an item")
async def create_item(item: Item):
    """
    Create an item with all the information:
    - **name**: each item must have a name
    - **description**: a long description
    - **price**: required
    - **tax**: if the item doesn't have tax, you can omit this
    - **tags**: a set of unique tag strings for this item
    \f
    :param item: User input.
    """
    return item