Body - 欄位¶

🌐 AI 與人類共同完成的翻譯

此翻譯由人類指導的 AI 完成。🤝

可能會有對原意的誤解，或讀起來不自然等問題。🤖

就像你可以在「路徑操作函式 (path operation function)」的參數中用 Query、Path 和 Body 宣告額外的驗證與中繼資料一樣，你也可以在 Pydantic 模型中使用 Pydantic 的 Field 來宣告驗證與中繼資料。

匯入 `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

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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

Warning

請注意，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

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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 等時，它們其實是回傳特殊類別的函式。

Tip

注意，每個帶有型別、預設值與 Field 的模型屬性，其結構和「路徑操作函式」的參數相同，只是把 Path、Query、Body 換成了 Field。

加入額外資訊¶

你可以在 Field、Query、Body 等中宣告額外資訊。這些資訊會被包含在產生的 JSON Schema 中。

你會在後續文件中學到更多關於加入額外資訊的內容，特別是在宣告範例時。

Warning

傳入 Field 的額外鍵也會出現在你的應用程式所產生的 OpenAPI schema 中。由於這些鍵不一定屬於 OpenAPI 規格的一部分，一些 OpenAPI 工具（例如 OpenAPI 驗證器）可能無法處理你產生的 schema。

回顧¶

你可以使用 Pydantic 的 Field 為模型屬性宣告額外的驗證與中繼資料。

你也可以使用額外的關鍵字引數來傳遞額外的 JSON Schema 中繼資料。

Body - 欄位¶

匯入 Field¶

宣告模型屬性¶

加入額外資訊¶

回顧¶

匯入 `Field`¶