FastAPI教程 路径操作配置
您可以将几个参数传递给路径操作装饰器来配置它。
警告
请注意，这些参数直接传递给路径操作装饰器，而不是您的路径操作函数。
响应状态码
您可以定义status_code要在您的路径操作的响应中使用的 (HTTP) 。
您可以直接传递int代码，例如404.
但是，如果您不记得每个数字代码的用途，您可以使用 中的快捷常量status：
from typing import Optional, Set
from fastapi import FastAPI, status
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[float] = None
tags: Set[str] = []
@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
return item
该状态代码将在响应中使用，并将添加到 OpenAPI 架构中。
技术细节
您也可以使用from starlette import status.
FastAPI提供相同starlette.status的fastapi.status，就像为你的方便，开发人员。但它直接来自Starlette。
标签
您可以向路径操作添加标签，tags使用listof str（通常只有一个str）传递参数：
from typing import Optional, Set
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[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 模式并由自动文档接口使用：
总结和描述
您可以添加一个summary和description：
from typing import Optional, Set
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[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
来自文档字符串的描述
由于描述往往很长并且涵盖多行，您可以在函数docstring 中声明路径操作描述，FastAPI将从那里读取它。
您可以在 docstring 中编写Markdown，它将被正确解释和显示（考虑到 docstring 缩进）。
from typing import Optional, Set
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[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 Optional, Set
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[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，但不删除它，请传递参数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"}]
它将在交互式文档中明确标记为已弃用：
检查已弃用和未弃用的路径操作的样子：
回顾
通过将参数传递给路径操作装饰器，您可以轻松地为路径操作配置和添加元数据。