Тело запроса¶

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

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

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

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

ИмпортируйтеBaseModel из Pydantic¶

Первое, что нужно сделать, — импортироватьBaseModel из пакетаpydantic:

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.post("/items/")asyncdefcreate_item(item:Item):returnitem

Создайте модель данных¶

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

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

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.post("/items/")asyncdefcreate_item(item:Item):returnitem

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

Например, модель выше описывает такой JSON "object" (или Pythondict):

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

...так какdescription иtax являются необязательными (со значением по умолчаниюNone), такой JSON "object" тоже будет корректным:

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

Объявите её как параметр¶

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

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.post("/items/")asyncdefcreate_item(item:Item):returnitem

...и укажите тип параметра как созданную вами модель,Item.

Результаты¶

Всего лишь с этой аннотацией типов PythonFastAPI:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.post("/items/")asyncdefcreate_item(item:Item):item_dict=item.model_dump()ifitem.taxisnotNone:price_with_tax=item.price+item.taxitem_dict.update({"price_with_tax":price_with_tax})returnitem_dict

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

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

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

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):return{"item_id":item_id,**item.model_dump()}

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

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

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

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item,q:str|None=None):result={"item_id":item_id,**item.model_dump()}ifq:result.update({"q":q})returnresult

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

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

Без Pydantic¶

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