Шаг 3 – Валидация параметров маршрутов (Path, Query)

Query

Дополнительно для работы с параметрами строки запроса фреймворк предоставляет класс Query из пакета fastapi. Класс Query позволяет прежде всего валидировать значения параметров строки запроса. В частности, через конструктор Query можно установить следующие параметры для валидации значений:

Общие метаданные:

title
description
example
include_in_schema

Специфичные правила валидации для строк:

min_length: устанавливает минимальное количество символов в значении параметра
max_length: устанавливает максимальное количество символов в значении параметра
regex: устанавливает регулярное выражение, которому должно соответствовать значение параметра
lt: значение параметра должно быть меньше определенного значения
le: значение параметра должно быть меньше или равно определенному значению
gt: значение параметра должно быть больше определенного значения
ge: значение параметра должно быть больше или равно определенному значению

Теперь, когда мы рассмотрели в прошлом разделе Annotated, будем использовать ее, и добавим Query со значением параметра max_length равным 10:

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/user/{username}")
async def login(
        username: Annotated[str, Path(min_length=3, max_length=15, description='Enter your username', example='permin0ff')],
        first_name: Annotated[str | None, Query(max_length=10)] = None) -> dict:
    return {"user": username, "Name": first_name}

Обратите внимание, что значение по умолчанию всё ещё None, так что параметр запроса будет необязательным. Давайте запустим приложение и попробуем передать запрос, например по адресу http://127.0.0.1:8000/user/permin0ff?first_name=Ilya мы увидим следующий вывод:

В случае если мы не будем передавать параметры запроса, например http://127.0.0.1:8000/user/permin0ff, то получим вывод:

Отдельно хотелось бы уточнить, что для Python 3.10 и выше мы можем сделать параметр не обязательным, указав:

first_name: Annotated[str | None, Query()] = None)

Когда Query используется внутри Annotated, вы не можете использовать параметр default у Query. Вместо этого, используйте обычное указание значения по умолчанию для параметра функции.

first_name: Annotated[str | None, Query()] = "Tomas")

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

first_name: Annotated[str, Query(max_length=10)] = ...)

Если по каким-то причинам мы хотим использовать Query без Annotated, то следует использовать следующий синтаксис:

first_name: str | None = Query(default=None, max_length=10))

Также с помощью параметра include_in_schema мы можем исключить данный параметр из документации.

first_name: str | None = Query(default=None, include_in_schema=False)

И теперь если мы перейдем в документацию, http://127.0.0.1:8000/docs/, то увидим отсутствующее поле: