您可以将几个参数传递给路径操作装饰器以对其进行配置。
警告
注意这些参数直接传递到 路径装饰器，而不是传递到 路径操作函数。
一、响应状态码
您可以自定义HTTP状态码使用在路径函数的响应中。
您可以直接传递int类型的状态码，比如 404。
但是，如果您不记得每个数字代码的用途，则可以使用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
这些状态码在响应中使用，并且会被添加到OpenAPI schema中。
二、标记(Tags)
你可以给路径操作函数添加标记，通过tags参数，参数类型可以是list或者str(一般是一个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"}]
这些标记将会被添加到OpenAPI schema中，在自动文旦的交互页面中可查看:
三、总结(summary)和描述(description)
你可以添加 summary 或 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
四、来自文档字符串的描述
如果描述很长或者包含多行文字，你可以申明路径操作描述在函数中，并且 FastAPI 也会从这里读取。
你可以在书写Markdown语法的文档描述串，它也可以被正确显示。
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
在交互文档中，显示如下：
五、响应描
你可以使用参数 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
说明
请注意，response_description特别是指响应，description一般是指路径操作。
OpenAPI指定每个路径操作都需要响应描述。
因此，如果您不提供任何一种，** FastAPI **将自动生成“成功响应”之一。
六、弃用路径操作
如果你想要弃用一个路径操作，但是又不想删除它，可以给路径操作函数传递一个参数 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"}]
在交互式文档中，它将明确标记为不推荐使用：
检查不赞成和不赞成使用的路径操作的样子：
网友评论