Skip to content

От переводчика

Это машинный перевод (DeepSeek) статьи https://fastapi.tiangolo.com/tutorial/body-fields/

Версия от 03.09.2026

Неочевидных моментов в уроке не обнаружено, но я рад сообщить, что дополнил базу инструмента для импорта модулей и классов в python классами, использующимися в уроке.

Подпишитесь на канал "Изучаем FastAPI", чтобы ссылки на инструмент работала.

 

Перевод прочих разделов документации буду по мере сил делать.

Обо мне

Тело запроса — поля

Точно так же, как вы можете объявлять дополнительную валидацию и метаданные в параметрах функции операции пути с помощью 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
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с 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, а не из fastapi, как все остальные (Query, Path, Body и т.д.).

Объявление атрибутов модели

Затем вы можете использовать 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
🤓 Другие версии и варианты

Совет

По возможности предпочитайте версию с 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, который сам является подклассом класса FieldInfo из Pydantic.

А Field из Pydantic также возвращает экземпляр FieldInfo.

Body также напрямую возвращает объекты подкласса FieldInfo. И есть другие, которые вы увидите позже и которые являются подклассами класса Body.

Помните, что когда вы импортируете Query, Path и другие из fastapi, на самом деле это функции, возвращающие специальные классы.

Совет

Обратите внимание, что каждый атрибут модели с типом, значением по умолчанию и Field имеет ту же структуру, что и параметр функции операции пути, только с Field вместо Path, Query и Body.

Добавление дополнительной информации

Вы можете объявить дополнительную информацию в Field, Query, Body и т.д. И она будет включена в сгенерированную JSON Schema.

Вы узнаете больше о добавлении дополнительной информации позже в документации, когда будете изучать объявление примеров.

Предупреждение

Дополнительные ключи, переданные в Field, также будут присутствовать в результирующей схеме OpenAPI для вашего приложения. Поскольку эти ключи не обязательно являются частью спецификации OpenAPI, некоторые инструменты OpenAPI, например валидатор OpenAPI, могут не работать с вашей сгенерированной схемой.

Итог

Вы можете использовать Field из Pydantic для объявления дополнительных валидаций и метаданных для атрибутов модели.

Вы также можете использовать дополнительные именованные аргументы для передачи дополнительных метаданных JSON Schema.