Path Operation Configuration

There are several parameters that you can pass to your path operation decorator to configure it.

Warning

Notice that these parameters are passed directly to the path operation decorator, not to your path operation function.

Response Status Code

You can define the (HTTP) status_code to be used in the response of your path operation.

You can pass directly the int code, like 404.

But if you don't remember what each number code is for, you can use the shortcut constants from starlette:

from typing import Set

from fastapi import FastAPI
from pydantic import BaseModel
from starlette.status import HTTP_201_CREATED

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None
    tags: Set[str] = []


@app.post("/items/", response_model=Item, status_code=HTTP_201_CREATED)
async def create_item(*, item: Item):
    return item

That status code will be used in the response and will be added to the OpenAPI schema.

Tags

You can add tags to your path operation, pass the parameter tags with a list of str (commonly just one str):

from typing import Set

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None
    tags: Set[str] = []


@app.post("/items/", response_model=Item, tags=["items"])
async def create_item(*, item: Item):
    return item


@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]

They will be added to the OpenAPI schema and used by the automatic documentation interfaces:

Summary and description

You can add a summary and description:

from typing import Set

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None
    tags: Set[str] = []


@app.post(
    "/items/",
    response_model=Item,
    summary="Create an item",
    description="Create an item with all the information, name, description, price, tax and a set of unique tags",
)
async def create_item(*, item: Item):
    return item

Description from docstring

As descriptions tend to be long and cover multiple lines, you can declare the path operation description in the function docstring and FastAPI will read it from there.

from typing import Set

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: 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
    """
    return item

It will be used in the interactive docs:

Info

OpenAPI specifies that descriptions can be written in Markdown syntax, but the interactive documentation systems included still don't support it at the time of writing this, although they have it in their plans.

Response description

You can specify the response description with the parameter response_description:

from typing import Set

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None
    tags: Set[str] = []


@app.post(
    "/items/",
    response_model=Item,
    summary="Create an item",
    response_description="The created 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
    """
    return item

Info

Notice that response_description refers specifically to the response, the description refers to the path operation in general.

Info

OpenAPI specifies that each path operation requires a response description.

So, if you don't provide one, FastAPI will automatically generate one of "Successful response".

Deprecate a path operation

If you need to mark a path operation as deprecated, but without removing it, pass the parameter deprecated:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]


@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
    return [{"item_id": "Foo"}]

It will be clearly marked as deprecated in the interactive docs:

Check how deprecated and non-deprecated path operations look like:

Recap

You can configure and add metadata for your path operations easily by passing parameters to the path operation decorators.