Как в FastAPI объявить эндпоинт, принимающий параметр прямо из пути URL, и как FastAPI определяет его тип?

Короткий ответ

Параметр пути объявляется как обычный аргумент функции-обработчика с тем же именем, что и в шаблоне пути; тип задаётся аннотацией типа, и FastAPI сам выполняет преобразование и валидацию.

Как это работает подробнее

FastAPI анализирует строку маршрута (например, /items/{item_id}) и сопоставляет плейсхолдеры с именами параметров функции. Аннотация типа (int, str, UUID и т. д.) используется Pydantic/Starlette для преобразования строки из URL и для генерации схемы OpenAPI.

Пример кода

example.pyКопировать

from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}
# GET /items/42       -> 200 {"item_id": 42}
# GET /items/abc       -> 422, т.к. "abc" нельзя привести к int

Что использовать на практике

• Практика. Если тип указан как int, а в URL передана не-числовая строка, FastAPI вернёт 422 Unprocessable Entity ещё до выполнения тела функции. Это удобно для базовой валидации без написания ручных проверок.

Подводные камни

• Риск. Забывают, что имя параметра в функции должно точно совпадать с именем в шаблоне пути; также путают Path(...) (для доп. ограничений, например gt=0) с простой аннотацией типа.