Компоненты пути и параметра запроса URL-адреса являются пользовательскими вводами. Следовательно, важно, чтобы их значения соответствовали определенным предопределенным критериям, прежде чем они будут перенаправлены в функцию, чтобы сервер не выбрасывал нежелательные исключения.

Во всех примерах кода, используемых до сих пор в этом курсе, параметры пути и запроса были объявлены стандартными типами Python - мы использовали int и str, но мы также можем использовать float и bool. Однако функция операции FastAPI может иметь путь или параметр запроса в качестве объекта класса Path или Query. Оба этих класса доступны внутри модуля fastapi.

Path

Первым делом рассмотрим класс Path, который отличает параметры пути от других аргументов, присутствующих в функции маршрута. Класс Path также помогает дать параметрам маршрута больше контекста во время документации, автоматически предоставляемой OpenAPI через Swagger и ReDoc, и действует как валидатор.

В частности, через конструктор Path можно установить следующие параметры для валидации значений:

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

• title
• description
• example
• include_in_schema

Специфичные правила валидации:

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

Рассмотрим некоторые возможности. Давайте переделаем код из прошлого раздела, добавив возможности класса Path:

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/user/{username}/{age}")
async def login(username: str = Path(min_length=3, max_length=15, description='Enter your username', example='Ilya'),
                age: int = Path(ge=0, le=100, description="Enter your age")) -> dict:
    return {"user": username, "age": age}

Давайте разберемся в данном коде, первым делом мы должны заметить изменения в декораторе, а именно изменился путь, так как класс Path работает только с параметрами пути, мы изменили путь на /user/{username}/{age}

Далее поле код username: str, из прошлого раздела, мы изменили на username: str = Path(min_length=3, max_length=15, description='Enter your username', example='Ilya'). Добавив проверку на минимальную и максимальную длину имени. Также мы добавили описание поля и добавили в поле пример имени.

Код age: int | None = None мы изменили на age: int = Path(ge=0, le=100, description="Enter your age"). Мы установили границы числа для поля age от 0 до 100 и добавили описание поля.

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

У нас появилось описание поля и пример ввода имени. Давайте попробуем передать данные:

В данном случае мы успешно прошли валидацию, и наша функция отработала и вернула правильный ответ. Теперь давайте попробуем передать ей те параметры, которые не пройдут валидацию:

Мы видим что параметр пути name длиной менее 3 символов, а параметр age это число более 100. В результате проверка не была пройдена.

Также в случае, если мы перейдем по адресу http://127.0.0.1:8000/user/ilya/33, мы получим результат выполнения функции. Но в случае, если мы перейдем по адресу http://127.0.0.1:8000/user/ilya/105 мы получим следующую ошибку валидации:

{
    "detail": [
        {
            "type": "less_than_equal",
            "loc": [
                "path",
                "age"
            ],
            "msg": "Input should be less than or equal to 100",
            "input": "105",
            "ctx": {
                "le": 100
            },
            "url": "https://errors.pydantic.dev/2.5/v/less_than_equal"
        }
    ]
}