Skip to content

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

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

Версия от 03.09.2026

По этой теме хочу также рекомендовать моё дополнение, как разрешить приём запросов со сторонних доменов.

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

 

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

Обо мне

Тело запроса

Когда вам нужно отправить данные от клиента (скажем, из браузера) в ваш API, вы отправляете их как тело запроса.

Тело запроса — это данные, отправляемые клиентом в ваш API. Тело ответа — это данные, которые ваш API отправляет клиенту.

Ваш API почти всегда должен отправлять тело ответа. Но клиентам не обязательно всегда отправлять тела запросов; иногда они лишь запрашивают путь, возможно, с некоторыми параметрами запроса, но не отправляют тело.

Чтобы объявить тело запроса, вы используете модели Pydantic со всей их мощью и преимуществами.

Примечание

Для отправки данных следует использовать один из методов: POST (наиболее распространённый), PUT, DELETE или PATCH.

Отправка тела с запросом GET имеет неопределённое поведение в спецификациях, тем не менее, она поддерживается FastAPI, только для очень сложных/экстремальных случаев использования.

Поскольку это не рекомендуется, интерактивная документация Swagger UI не будет показывать документацию для тела при использовании GET, а промежуточные прокси могут её не поддерживать.

Импорт BaseModel из Pydantic

Сначала вам нужно импортировать BaseModel из pydantic:

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

Создайте свою модель данных

Затем вы объявляете свою модель данных как класс, наследующий от BaseModel.

Используйте стандартные типы Python для всех атрибутов:

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

Как и при объявлении параметров запроса, когда атрибут модели имеет значение по умолчанию, он не является обязательным. В противном случае он обязателен. Используйте None, чтобы сделать его просто необязательным.

Например, эта модель выше объявляет JSON-«object» (или Python dict) вида:

{
    "name": "Foo",
    "description": "An optional description",
    "price": 45.2,
    "tax": 3.5
}

...поскольку description и tax необязательны (со значением по умолчанию None), этот JSON-«object» также будет допустимым:

{
    "name": "Foo",
    "price": 45.2
}

Объявите его как параметр

Чтобы добавить его в вашу операцию пути, объявите его так же, как вы объявляли параметры пути и запроса:

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

...и объявите его тип как созданную вами модель, Item.

Результаты

Благодаря одному лишь этому объявлению типа Python, FastAPI сможет:

  • Прочитать тело запроса как JSON.
  • Преобразовать соответствующие типы (при необходимости).
  • Провести валидацию данных.
    • Если данные недействительны, он вернёт понятную и чёткую ошибку, указывающую, где именно и какие данные были некорректными.
  • Передать вам полученные данные в параметре item.
    • Поскольку вы объявили его в функции как тип Item, вы также получите всю поддержку редактора (автодополнение и т. д.) для всех атрибутов и их типов.
  • Сгенерировать определения JSON Schema для вашей модели; вы также можете использовать их где угодно ещё, если это имеет смысл для вашего проекта.
  • Эти схемы станут частью сгенерированной схемы OpenAPI и будут использоваться автоматической документацией UI.

Автоматическая документация

JSON-схемы ваших моделей станут частью сгенерированной схемы OpenAPI и будут показаны в интерактивной документации API:

А также будут использоваться в документации API внутри каждой операции пути, которой они нужны:

Поддержка редактора

В вашем редакторе внутри функции вы получите подсказки типов и автодополнение повсюду (этого бы не произошло, если бы вы получали dict вместо модели Pydantic):

Вы также получаете проверки ошибок для некорректных операций с типами:

Это не случайность — весь фреймворк был построен вокруг такого дизайна.

И он был тщательно протестирован на этапе проектирования, до какой-либо реализации, чтобы гарантировать его работу со всеми редакторами.

Были даже некоторые изменения в самом Pydantic для поддержки этого.

Предыдущие скриншоты были сделаны в Visual Studio Code.

Но вы получите такую же поддержку редактора в PyCharm и большинстве других редакторов Python:

Совет

Если вы используете PyCharm в качестве редактора, вы можете использовать плагин Pydantic для PyCharm.

Он улучшает поддержку редактора для моделей Pydantic, включая:

  • автодополнение
  • проверку типов
  • рефакторинг
  • поиск
  • инспекции

Использование модели

Внутри функции вы можете напрямую обращаться ко всем атрибутам объекта модели:

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.model_dump()
    if item.tax is not None:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

Тело запроса + параметры пути

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

FastAPI распознает, что параметры функции, совпадающие с параметрами пути, должны быть взяты из пути, а параметры функции, объявленные как модели Pydantic, должны быть взяты из тела запроса.

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.model_dump()}

Тело запроса + параметры пути + параметры запроса

Вы также можете объявлять параметры тела, пути и запроса — все одновременно.

FastAPI распознает каждый из них и возьмёт данные из правильного места.

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result.update({"q": q})
    return result

Параметры функции будут распознаны следующим образом:

  • Если параметр также объявлен в пути, он будет использоваться как параметр пути.
  • Если параметр имеет единичный тип (например, int, float, str, bool и т. д.), он будет интерпретирован как параметр запроса.
  • Если параметр объявлен как тип модели Pydantic, он будет интерпретирован как тело запроса.

Примечание

FastAPI поймёт, что значение q не является обязательным, из-за значения по умолчанию = None.

str | None не используется FastAPI для определения того, что значение не является обязательным; он поймёт, что оно необязательно, потому что у него есть значение по умолчанию = None.

Но добавление аннотаций типов позволит вашему редактору обеспечить лучшую поддержку и обнаруживать ошибки.

Без Pydantic

Если вы не хотите использовать модели Pydantic, вы также можете использовать параметры Body. Смотрите документацию по Body - Несколько параметров: единичные значения в теле.