请求体 - 字段¶
就像你可以使用 Query、Path 和 Body 在路径操作函数参数中声明额外的验证和元数据一样，你也可以使用 Pydantic 的 Field 在 Pydantic 模型内部声明验证和元数据。
导入 Field¶
首先，你需要导入它
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
🤓 其他版本和变体
from typing import Annotated, Union
from fastapi import Body, FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[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: Union[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
from typing import Union
from fastapi import Body, FastAPI
from pydantic import BaseModel, Field
from typing_extensions import Annotated
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[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: Union[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
提示
如果可能，请优先使用 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
提示
如果可能，请优先使用 Annotated 版本。
from typing import Union
from fastapi import Body, FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[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: Union[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 与模型属性一起使用
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
🤓 其他版本和变体
from typing import Annotated, Union
from fastapi import Body, FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[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: Union[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
from typing import Union
from fastapi import Body, FastAPI
from pydantic import BaseModel, Field
from typing_extensions import Annotated
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[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: Union[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
提示
如果可能，请优先使用 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
提示
如果可能，请优先使用 Annotated 版本。
from typing import Union
from fastapi import Body, FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[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: Union[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 元数据。