Operation description
- Status code : Let’s the client know what the status of the response is.
- Response description: Gives information to client about the response
- Tags: Structuring the endpoints in different logical ways
- Summary and description: To provide more information about the endpoint
Status code
It indicates the status of the response. It can be 200, 201, 400, 404, 500, etc. It is defined in the status_code parameter of the @myApp.get decorator.
@myApp.get("/items/{item_id}", status_code=404)
def read_item(item_id: int):
if item_id != 0:
return {"message": f"Item with id {item_id}"}
else:
return {"message": f"Item with id {item_id} not found"}
The FastAPI provides a status object that contains all the status codes. We can use it to make the code more readable.
from fastapi import status
@myApp.get("/items/{item_id}", status_code=status.HTTP_404_NOT_FOUND)
# no matter which condition is true, it will return the status code 404
def read_item(item_id: int):
if item_id != 0:
return {"message": f"Item with id {item_id}"}
else:
return {"message": f"Item with id {item_id} not found"}
To get a different status code for different conditions, we can use the status_code parameter of the return statement.
from fastapi import status, Response
@myApp.get("/items/{item_id}", status_code=status.HTTP_200_OK)
# pass response as a parameter
def read_item(item_id: int, response: Response):
if item_id != 0:
response.status_code = status.HTTP_200_OK
return {"message": f"Item with id {item_id}"}
else:
response.status_code = status.HTTP_404_NOT_FOUND
return {"message": f"Item with id {item_id} not found"}
Tags
Tags are used to group the endpoints in different logical ways. It is defined in the tags parameter of the @myApp.get decorator.
@myApp.get("/item/{id}/comments/{comment_id}", tags=["item", "comments"])
def get_comment(id: int, comment_id: int):
return {"message": f"Comment with id {comment_id} for item with id {id}"}
In the docs UI, the endpoints are grouped according to the tags.
Summary and description
Summary and description are used to provide more information about the endpoint. It is defined in the summary and description parameters of the @myApp.get decorator.
@myApp.get(
"/item/{id}/comments/{comment_id}",
tags=["item", "comments"],
summary="Get a comment",
description="Get a comment for a specific item"
)
def get_comment(id: int, comment_id: int):
return {"message": f"Comment with id {comment_id} for item with id {id}"}
The summary and description are shown in the docs UI. Another way to add description is to use the docstring.
@myApp.get(
"/item/{id}/comments/{comment_id}",
tags=["item", "comments"],
)
def get_comment(id: int, comment_id: int):
"""
Get a comment for a specific item
- **id**: Mandatory item id
- **comment_id**: Mandatory comment id
"""
return {"message": f"Comment with id {comment_id} for item with id {id}"}
Response description
Response description is used to provide more information about the response. It is defined in the response_description parameter of the return statement.
@myApp.get(
"/item/{id}/comments/",
tags=["item", "comments"],
summary="Get a comment",
description="Get a comment for a specific item",
response_description="The list of available Comments"
)
def get_comment(id: int):
# return a list of comments