Аннотации в FastAPI
Библиотека FastAPI позволяет использовать аннотации для параметров функций, обеспечивая проверку данных на этапе получения. Некорректные данные вызывают ошибку, что полезно как для разработчика серверной части, так и для клиента, получающего понятные сообщения об ошибках.
Подключение необходимых классов
Для работы с аннотациями подключим необходимые классы: Annotated из typing и Path из FastAPI.
from fastapi import Path
from typing import AnnotatedВалидация параметров
Динамический параметр
Рассмотрим функцию с динамическим параметром (например, Items с параметром id). Добавим валидацию для item_id:
@app.get("/items/{item_id}")
async def read_item(item_id: Annotated[int, Path(title="ID поста")]):
# ...Вместо простого указания типа (int), используется Annotated[int, Path(title="ID поста")]. Path добавляет описание параметра (title), отображаемое в документации ReDoc.
Параметры запроса
Валидация параметров, передаваемых через знак вопроса в URL (query parameters), осуществляется с помощью Query:
from fastapi import Query
@app.get("/search")
async def search(id: Annotated[Optional[int], Query(title="ID поста для поиска", ge=1, le=50)] = None):
# ...Параметр id необязателен (Optional[int]) и имеет диапазон значений от 1 до 50.
Параметры тела запроса
Валидация тела запроса выполняется с помощью Body:
from fastapi import Body
from pydantic import BaseModel, Field
class UserCreate(BaseModel):
name: Annotated[str, Field(..., title="Имя пользователя", min_length=2, max_length=20)]
age: Annotated[int, Field(..., title="Возраст пользователя", ge=1, le=120)]
@app.post("/users")
async def create_user(user: Annotated[UserCreate, Body(..., example={"name": "username", "age": 1})]):
# ...Body использует класс UserCreate для валидации. example показывает пример корректных данных.
Дополнительные проверки с Annotated
Annotated позволяет добавлять различные проверки:
- …: обязательный параметр.
- ge: greater than or equal (больше или равно).
- le: less than or equal (меньше или равно).
- max_length: максимальная длина строки (для str).
- min_length: минимальная длина строки (для str).
Пример использования дополнительных проверок:
@app.get("/items/{item_id}")
async def read_item(item_id: Annotated[int, Path(..., title="ID поста", ge=1, le=100)]):
# ...item_id должен быть числом от 1 до 100 включительно и обязателен для передачи.
Документация
FastAPI поддерживает два формата документации: Swagger UI (/docs) и ReDoc (/redoc). Описание параметра через Path(title="…"), Query(title="…") и Field(title="…") отображается в ReDoc.
Использование Annotated с Path, Query, Field и Body упрощает валидацию данных в FastAPI, улучшает читаемость кода и качество документации. Это значительно упрощает разработку и взаимодействие с API.