Path Operation Configuration¶
There are several parameters that you can pass to yourpath operation decorator to configure it.
Warning
Notice that these parameters are passed directly to thepath operation decorator, not to yourpath operation function.
Response Status Code¶
You can define the (HTTP)status_code to be used in the response of yourpath operation.
You can pass directly theint code, like404.
But if you don't remember what each number code is for, you can use the shortcut constants instatus:
fromfastapiimportFastAPI,statusfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()@app.post("/items/",status_code=status.HTTP_201_CREATED)asyncdefcreate_item(item:Item)->Item:returnitemThat status code will be used in the response and will be added to the OpenAPI schema.
Technical Details
You could also usefrom starlette import status.
FastAPI provides the samestarlette.status asfastapi.status just as a convenience for you, the developer. But it comes directly from Starlette.
Tags¶
You can add tags to yourpath operation, pass the parametertags with alist ofstr (commonly just onestr):
fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()@app.post("/items/",tags=["items"])asyncdefcreate_item(item:Item)->Item:returnitem@app.get("/items/",tags=["items"])asyncdefread_items():return[{"name":"Foo","price":42}]@app.get("/users/",tags=["users"])asyncdefread_users():return[{"username":"johndoe"}]They will be added to the OpenAPI schema and used by the automatic documentation interfaces:
Tags with Enums¶
If you have a big application, you might end up accumulatingseveral tags, and you would want to make sure you always use thesame tag for relatedpath operations.
In these cases, it could make sense to store the tags in anEnum.
FastAPI supports that the same way as with plain strings:
fromenumimportEnumfromfastapiimportFastAPIapp=FastAPI()classTags(Enum):items="items"users="users"@app.get("/items/",tags=[Tags.items])asyncdefget_items():return["Portal gun","Plumbus"]@app.get("/users/",tags=[Tags.users])asyncdefread_users():return["Rick","Morty"]Summary and description¶
You can add asummary anddescription:
fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()@app.post("/items/",summary="Create an item",description="Create an item with all the information, name, description, price, tax and a set of unique tags",)asyncdefcreate_item(item:Item)->Item:returnitemDescription from docstring¶
As descriptions tend to be long and cover multiple lines, you can declare thepath operation description in the functiondocstring andFastAPI will read it from there.
You can writeMarkdown in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation).
fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()@app.post("/items/",summary="Create an item")asyncdefcreate_item(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 """returnitemIt will be used in the interactive docs:
Response description¶
You can specify the response description with the parameterresponse_description:
fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()@app.post("/items/",summary="Create an item",response_description="The created item",)asyncdefcreate_item(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 """returnitemInfo
Notice thatresponse_description refers specifically to the response, thedescription refers to thepath operation in general.
Check
OpenAPI specifies that eachpath operation requires a response description.
So, if you don't provide one,FastAPI will automatically generate one of "Successful response".
Deprecate apath operation¶
If you need to mark apath operation asdeprecated, but without removing it, pass the parameterdeprecated:
fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/",tags=["items"])asyncdefread_items():return[{"name":"Foo","price":42}]@app.get("/users/",tags=["users"])asyncdefread_users():return[{"username":"johndoe"}]@app.get("/elements/",tags=["items"],deprecated=True)asyncdefread_elements():return[{"item_id":"Foo"}]It will be clearly marked as deprecated in the interactive docs:
Check how deprecated and non-deprecatedpath operations look like:
Recap¶
You can configure and add metadata for yourpath operations easily by passing parameters to thepath operation decorators.