Когда вам нужно отправить данные от клиента (скажем, из браузера) в ваш API, вы отправляете их как тело запроса.
Тело запроса — это данные, отправляемые клиентом в ваш API. Тело ответа — это данные, которые ваш API отправляет клиенту.
Ваш API почти всегда должен отправлять тело ответа. Но клиентам не обязательно всегда отправлять тела запросов; иногда они лишь запрашивают путь, возможно, с некоторыми параметрами запроса, но не отправляют тело.
Чтобы объявить тело запроса, вы используете модели Pydantic со всей их мощью и преимуществами.
Примечание
Для отправки данных следует использовать один из методов: POST (наиболее распространённый), PUT, DELETE или PATCH.
Отправка тела с запросом GET имеет неопределённое
поведение в спецификациях, тем не менее, она поддерживается
FastAPI, только для очень сложных/экстремальных случаев использования.
Поскольку это не рекомендуется, интерактивная документация Swagger UI не будет показывать документацию для тела при использовании GET, а промежуточные прокси могут её не поддерживать.
Как и при объявлении параметров запроса, когда атрибут модели
имеет значение по умолчанию, он не является обязательным. В противном случае он обязателен. Используйте None, чтобы сделать его просто необязательным.
Например, эта модель выше объявляет JSON-«object» (или Python dict) вида:
В вашем редакторе внутри функции вы получите подсказки типов и автодополнение повсюду (этого бы не произошло, если бы вы получали dict вместо модели Pydantic):
Вы также получаете проверки ошибок для некорректных операций с типами:
Это не случайность — весь фреймворк был построен вокруг такого дизайна.
И он был тщательно протестирован на этапе проектирования, до какой-либо реализации, чтобы гарантировать его работу со всеми редакторами.
Были даже некоторые изменения в самом Pydantic для поддержки этого.
Вы можете объявлять параметры пути и тело запроса одновременно.
FastAPI распознает, что параметры функции, совпадающие с параметрами пути, должны быть взяты из пути, а параметры функции, объявленные как модели Pydantic, должны быть взяты из тела запроса.
Параметры функции будут распознаны следующим образом:
Если параметр также объявлен в пути, он будет использоваться как параметр пути.
Если параметр имеет единичный тип (например, int, float, str, bool и т. д.), он будет интерпретирован как параметр запроса.
Если параметр объявлен как тип модели Pydantic, он будет интерпретирован как тело запроса.
Примечание
FastAPI поймёт, что значение q не является обязательным, из-за значения по умолчанию = None.
str | None не используется FastAPI для определения того,
что значение не является обязательным; он поймёт, что оно необязательно, потому что у него
есть значение по умолчанию = None.
Но добавление аннотаций типов позволит вашему редактору обеспечить лучшую поддержку и обнаруживать ошибки.