21_路径操作配置
21_路径操作配置
路径操作装饰器支持使用多种参数进行配置。
警告：以下参数应直接传递给路径操作装饰器，而不是路径操作函数。
1. 响应状态码：
我们可以使用 status_code 参数定义路径操作响应的状态码。
直接给他传递一个 int值，如404。
但是，如果不记得每个数字代表的含义了，可以使用status快捷常量：
from fastapi import FastAPI, status
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED) # 设置响应状态码为201
async def create_item(item: Item):
return item
这样状态码就会被添加到响应中，同时也添加到 OpenAPI schema中。
技术细节：
也可以使用
from starlette import status导入状态码。FastAPI 的
fastapi.status和starlette.status一样，只是快捷方式。实际上，fastapi.status直接继承自 Starlette。
2. 标签 tags：
可以为路径操作添加标签，给tags参数传递一个str列表（通常只有一个str):
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", response_model=Item, tags=["items"]) # 添加items tag
async def create_item(item: Item):
return item
@app.get("/items/", tags=["items"]) # 添加items tag
async def read_items():
return [{"name": "Foo", "price": 42}]
@app.get("/users/", tags=["users"]) # 添加users tag
async def read_users():
return [{"username": "johndoe"}]
这些标签将被添加到 OpenAPI Schema中，并由自动文档接口使用:
带枚举的标签：
如果我们有一个大型应用，那么最终可能会累积很多个标签，并且我们希望确保对于相关的路径操作始终使用相同的标签。
在这种情况下，将标签储存在 枚举Enmu 中就显得很有必要了。
FastAPI支持枚举，就像普通的字符串一样：
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"]
3. summary 与 description 参数：
路径装饰器还支持 summary 和 description 这两个参数, 用来描述路径操作。
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: 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
4. 从文档字符串（docstring）进行描述：
由于描述往往很长并且覆盖多行，可以在函数 docstring(一个多行的字符串，是函数中的第一个表达式（并未分配给任何变量），用来作为文档信息) 中声明路径操作描述，FastAPI将从那里读取它。
我们可以在 docstring 中使用Markdown格式，他将被正确的解释和显示（考虑docstring缩进）。
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: 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
"""
# 以上文档字符串docstring将作为路径操作的description参数内容
return item
他将会被用在交互式文档中：
5. 响应描述：
可以通过response_description参数指定响应描述信息：
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@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
说明：
注意：
response_description只用于描述响应，description一般则用于描述路径操作。
检查：
OpenAPI 规定每个路径操作都要有响应描述。
如果没有定义响应描述，FastAPI 则自动生成内容为 “Successful response” 的响应描述。
6. 弃用路径操作：
如果想要将一个路径操作标记为 弃用deprecated (过时，不推荐再使用) ，但不想删除它，则可以使用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"}]
对应路径操作会在交互式文档中明确标记为弃用：
下图显示了正常路径操作与弃用路径操作 的区别：
总结：
通过将参数传递给路径操作装饰器，可以轻松地对路径操作进行配置和添加元数据。