路径操作配置

您可以将几个参数传递给路径操作装饰器以对其进行配置。

:::tips 警告
请注意，这些参数直接传递给路径操作装饰器，而不是传递给路径操作函数。 :::

响应状态码

您可以定义要在路径操作的响应中使用的（HTTP）status_code。
您可以直接传递int代码，例如404。
但是，如果您不记得每个数字代码的用途，则可以在status中使用快捷方式常量：

from typing import Set
from fastapi import FastAPI, status
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, status_code=status.HTTP_201_CREATED)
async def create_item(*, item: Item):
    return item

该状态代码将在响应中使用，并将添加到OpenAPI架构中。

:::info 你也可以使用from starlette import status
FastAPI提供与starlette.status相同的fastapi.status，以方便开发人员。但它直接来自Starlette。 :::

标签

您可以在路径操作中添加标签，并通过带有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架构中，并由自动文档界面使用：

总结和说明

你可以添加一个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

来自文档字符串的描述

由于描述可能会很长并且涵盖多行，因此您可以在函数docstring中声明路径操作描述，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

:::tips 请注意，response_description特别是指响应，description通常是指路径操作。 :::

:::info OpenAPI指定每个路径操作都需要响应描述。
因此，如果您不提供任何一种，FastAPI将自动生成“成功响应”之一。 :::

弃用路径操作

如果需要将路径操作标记为已弃用，但不删除它，则传递不建议使用的参数：

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"}]

在交互式文档中，它将明确标记为不推荐使用：

检查不赞成和不赞成使用的路径操作的样子：

概括

通过将参数传递给路径操作修饰符，可以轻松地为路径操作配置和添加元数据。