Как в FastAPI сделать query-параметр необязательным со значением по умолчанию?

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

Параметру функции задаётся обычное значение по умолчанию в сигнатуре (например, limit: int = 10); FastAPI автоматически трактует такой параметр как необязательный query-параметр.

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

Если параметр функции не встречается в шаблоне пути и имеет значение по умолчанию, FastAPI считает его query-параметром и подставляет значение по умолчанию, если клиент его не передал.

Пример кода

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

from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
def list_items(limit: int = Query(default=10, ge=1, le=100)):
    return {"limit": limit}
# GET /items/            -> {"limit": 10}
# GET /items/?limit=500   -> 422, т.к. превышено le=100

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

• Практика. Для дополнительных ограничений (минимум/максимум, описание в OpenAPI) используют Query(default=10, ge=1, le=100) вместо простого литерала — это не меняет поведение по умолчанию, но добавляет валидацию и документацию.

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

• Риск. Путают необязательность параметра с Optional[int] без значения по умолчанию (Optional[int] без = None всё равно формально обязателен для передачи null, но не для отсутствия ключа); не указывают разумные границы (ge/le) для параметров пагинации.