持续创作，加速成长！这是我参与「掘金日新计划 · 6 月更文挑战」的第23天，点击查看活动详情

响应状态码

• 在路径装饰器中使用status_code设置默认响应状态码，这个参数的值可以直接使用数字，也可以使用starlette提供的快捷常量。
• 虽然status.HTTP_201_CREATED是从fastapi中导出的，但其实本质使用的是startlette的快捷常量。
• 使用status_code的好处：1) 设置了响应状态码，2)在openapi文档显示。

 from typing import Set, Union
 ​
 from fastapi import FastAPI, status
 from pydantic import BaseModel
 ​
 app = FastAPI()
 ​
 ​
 class Item(BaseModel):
     name: str
     description: Union[str, None] = None
     price: float
     tax: Union[float, None] = None
     tags: Set[str] = set()
 ​
 ​
 @app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
 async def create_item(item: Item):
     return item

标签Tags

• 对于大型项目，api可能非常多，此时可以使用tags给api打标签分类显示，更好的管理api
• 其中：tags的值可以使用一个str, 也可以是str组成的列表

 from typing import Set, Union
 ​
 from fastapi import FastAPI
 from pydantic import BaseModel
 ​
 app = FastAPI()
 ​
 ​
 class Item(BaseModel):
     name: str
     description: Union[str, None] = None
     price: float
     tax: Union[float, None] = None
     tags: Set[str] = set()
 ​
 ​
 @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"}]

• 当然了tags的值也可以是枚举变量，这样就可以保整个项目中使用统一的标签集
• 如下例中，Tags类继承Enum,Tags类的每个成员都是字符串。

 from enum import Enum
 ​
 from fastapi import FastAPI
 ​
 app = FastAPI()
 ​
 ​
 class Tags(Enum):
     items = "items"
     users = "users"
 ​
 ​
 @app.get("/items/", tags=[Tags.items])
 async def get_items():
     return ["Portal gun", "Plumbus"]
 ​
 ​
 @app.get("/users/", tags=[Tags.users])
 async def read_users():
     return ["Rick", "Morty"]

描述信息

• 可以给api接口设置描述信息，此时可以使用：summary和description

 from typing import Set, Union
 ​
 from fastapi import FastAPI
 from pydantic import BaseModel
 ​
 app = FastAPI()
 ​
 ​
 class Item(BaseModel):
     name: str
     description: Union[str, None] = None
     price: float
     tax: Union[float, None] = None
     tags: Set[str] = set()
 ​
 ​
 @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

详细的文档信息

• 如果需要给api提供详细的，长段的描述信息，此时可以使用：文档注释的方式

 from typing import Set, Union
 ​
 from fastapi import FastAPI
 from pydantic import BaseModel
 ​
 app = FastAPI()
 ​
 ​
 class Item(BaseModel):
     name: str
     description: Union[str, None] = None
     price: float
     tax: Union[float, None] = None
     tags: Set[str] = set()
 ​
 ​
 @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

响应描述

• 给响应数据提供描述信息，使用：response_description

 from typing import Set, Union
 ​
 from fastapi import FastAPI
 from pydantic import BaseModel
 ​
 app = FastAPI()
 ​
 ​
 class Item(BaseModel):
     name: str
     description: Union[str, None] = None
     price: float
     tax: Union[float, None] = None
     tags: Set[str] = set()
 ​
 ​
 @app.post(
     "/items/",
     response_model=Item,
     response_description="The created item",
 )
 async def create_item(item: Item):
     return item

设置路径函是废弃的状态

• 如果一定接口不在使用了，但是又不想删除这个接口，此时可以使用：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"}]