From b5d92317bc9a559f557fe39eeedcd5ffa47dc151 Mon Sep 17 00:00:00 2001 From: Denys Fedoryshchenko Date: Tue, 3 Nov 2026 18:48:52 +0200 Subject: [PATCH] fix: keep pagination query defaults outside Annotated metadata FastAPI 0.162 rejects defaults embedded in Query metadata when fastapi-pagination registers its parameter dependency, preventing the API from importing at add_pagination(app). Define limit and offset with Annotated Query constraints and separate defaults. Override the inherited offset as well, preserving the default page size, offset, and unlimited maximum page size. Add regression coverage for pagination registration, defaults, offsets, large pages, invalid query parameters, and OpenAPI generation. Signed-off-by: Denys Fedoryshchenko --- api/models.py | 5 +- tests/unit_tests/test_pagination.py | 77 +++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 tests/unit_tests/test_pagination.py diff --git a/api/models.py b/api/models.py index 65ab0afb..19205738 100644 --- a/api/models.py +++ b/api/models.py @@ -282,7 +282,10 @@ class CustomLimitOffsetParams(LimitOffsetParams): The model is required to redefine limit parameter to remove the number validation on maximum value""" - limit: int = Query(50, ge=1, description="Page size limit") + # Keep defaults outside Query metadata for FastAPI's Annotated dependencies. + # Override offset too, as the inherited field also puts its default in Query. + limit: Annotated[int, Query(ge=1, description="Page size limit")] = 50 + offset: Annotated[int, Query(ge=0, description="Page offset")] = 0 class PageModel(LimitOffsetPage[TypeVar("T")]): diff --git a/tests/unit_tests/test_pagination.py b/tests/unit_tests/test_pagination.py new file mode 100644 index 00000000..d8bfc4cf --- /dev/null +++ b/tests/unit_tests/test_pagination.py @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: LGPL-2.1-or-later + +"""Regression tests for pagination dependency registration and query parameters.""" + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient +from fastapi_pagination import add_pagination, paginate + +from api.models import PageModel + + +@pytest.fixture +def pagination_client(): + """Register the API's pagination model without requiring a database.""" + app = FastAPI() + + @app.get("/items", response_model=PageModel[int]) + async def items(): + return paginate(list(range(200))) + + add_pagination(app) + with TestClient(app) as client: + yield client + + +@pytest.mark.parametrize( + "params, limit, offset", + [({}, 50, 0), ({"limit": 150, "offset": 3}, 150, 3), ({"limit": 1}, 1, 0)], +) +def test_pagination_query_parameters(pagination_client, params, limit, offset): + """Preserve defaults, offsets, and page sizes above the library's cap.""" + response = pagination_client.get("/items", params=params) + + assert response.status_code == 200 + assert response.json() == { + "items": list(range(200))[offset : offset + limit], + "total": 200, + "limit": limit, + "offset": offset, + } + + +@pytest.mark.parametrize( + "params, field", + [ + ({"limit": 0}, "limit"), + ({"limit": -1}, "limit"), + ({"offset": -1}, "offset"), + ({"limit": "invalid"}, "limit"), + ], +) +def test_invalid_pagination_query_parameters(pagination_client, params, field): + """Invalid pagination parameters remain request validation errors.""" + response = pagination_client.get("/items", params=params) + + assert response.status_code == 422 + assert response.json()["detail"][0]["loc"] == ["query", field] + + +def test_pagination_openapi(pagination_client): + """Expose optional query parameters with unchanged defaults and bounds.""" + response = pagination_client.get("/openapi.json") + + assert response.status_code == 200 + parameters = { + param["name"]: param + for param in response.json()["paths"]["/items"]["get"]["parameters"] + } + for name, default, minimum in [("limit", 50, 1), ("offset", 0, 0)]: + parameter = parameters[name] + assert parameter["in"] == "query" + assert parameter["required"] is False + assert parameter["schema"]["type"] == "integer" + assert parameter["schema"]["default"] == default + assert parameter["schema"]["minimum"] == minimum + assert "maximum" not in parameter["schema"]