Body - Fields¶

正如您可以使用 Query、Path 和 Body 在路径操作函数参数中声明额外的校验和元数据一样，您也可以使用 Pydantic 的 Field 在 Pydantic 模型内部声明校验和元数据。

导入 `Field`¶

首先，您必须导入它

Python 3.10+

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(gt=0, description="The price must be greater than zero")
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):
    results = {"item_id": item_id, "item": item}
    return results

🤓 其他版本和变体

Python 3.10+ - 非 Annotated

提示

如果可能，请优先使用 Annotated 版本。

from fastapi import Body, FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(gt=0, description="The price must be greater than zero")
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item = Body(embed=True)):
    results = {"item_id": item_id, "item": item}
    return results

警告

注意 Field 是直接从 pydantic 导入的，而不是像其他所有工具（Query、Path、Body 等）那样从 fastapi 导入的。

声明模型属性¶

然后，您可以在模型属性中使用 Field

Python 3.10+

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(gt=0, description="The price must be greater than zero")
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):
    results = {"item_id": item_id, "item": item}
    return results

🤓 其他版本和变体

Python 3.10+ - 非 Annotated

提示

如果可能，请优先使用 Annotated 版本。

from fastapi import Body, FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(gt=0, description="The price must be greater than zero")
    tax: float | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item = Body(embed=True)):
    results = {"item_id": item_id, "item": item}
    return results

Field 的工作方式与 Query、Path 和 Body 相同，它拥有完全相同的参数等。

技术细节

事实上，您稍后会看到的 Query、Path 等，它们创建的是通用 Param 类的子类对象，而 Param 类本身又是 Pydantic FieldInfo 类的子类。

同时，Pydantic 的 Field 返回的也是一个 FieldInfo 实例。

Body 也直接返回 FieldInfo 子类的对象。您稍后还会看到其他属于 Body 类子类的组件。

请记住，当您从 fastapi 导入 Query、Path 等时，它们实际上是返回特殊类的函数。

提示

请注意，每个带有类型、默认值和 Field 的模型属性，其结构与路径操作函数的参数结构是一样的，只是用 Field 替换了 Path、Query 和 Body。

添加额外信息¶

您可以在 Field、Query、Body 等中声明额外信息。这些信息将被包含在生成的 JSON Schema 中。

在后续文档中学习声明示例时，您将了解更多关于添加额外信息的知识。

警告

传递给 Field 的额外键也将出现在应用程序生成的 OpenAPI schema 中。由于这些键未必是 OpenAPI 规范的一部分，某些 OpenAPI 工具（例如 OpenAPI 验证器）可能无法处理您生成的 schema。

总结¶

您可以使用 Pydantic 的 Field 为模型属性声明额外的校验和元数据。

您还可以使用额外的关键字参数来传递附加的 JSON Schema 元数据。

Body - Fields¶

导入 Field¶

声明模型属性¶

添加额外信息¶

总结¶

导入 `Field`¶