diff --git a/docs/module/schemas.md b/docs/module/schemas.md index b92dc8c..d048844 100644 --- a/docs/module/schemas.md +++ b/docs/module/schemas.md @@ -22,16 +22,20 @@ async def get_user(user: User = UserDep) -> Response[UserSchema]: ### [`PaginatedResponse[T]`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse) -Wraps a list of items with pagination metadata and optional facet values. +Wraps a list of items with pagination metadata and optional facet values. The `pagination` field accepts either [`OffsetPagination`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPagination) or [`CursorPagination`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPagination) depending on the strategy used. + +#### [`OffsetPagination`](../reference/schemas.md#fastapi_toolsets.schemas.OffsetPagination) + +Page-number based. Requires `total_count` so clients can compute the total number of pages. ```python -from fastapi_toolsets.schemas import PaginatedResponse, Pagination +from fastapi_toolsets.schemas import PaginatedResponse, OffsetPagination @router.get("/users") async def list_users() -> PaginatedResponse[UserSchema]: return PaginatedResponse( data=users, - pagination=Pagination( + pagination=OffsetPagination( total_count=100, items_per_page=10, page=1, @@ -40,6 +44,26 @@ async def list_users() -> PaginatedResponse[UserSchema]: ) ``` +#### [`CursorPagination`](../reference/schemas.md#fastapi_toolsets.schemas.CursorPagination) + +Cursor based. Efficient for large or frequently updated datasets where offset pagination is impractical. Provides opaque `next_cursor` / `prev_cursor` tokens; no total count is exposed. + +```python +from fastapi_toolsets.schemas import PaginatedResponse, CursorPagination + +@router.get("/events") +async def list_events() -> PaginatedResponse[EventSchema]: + return PaginatedResponse( + data=events, + pagination=CursorPagination( + next_cursor="eyJpZCI6IDQyfQ==", + prev_cursor=None, + items_per_page=20, + has_more=True, + ), + ) +``` + The optional `filter_attributes` field is populated when `facet_fields` are configured on the CRUD class (see [Filter attributes](crud.md#filter-attributes-facets)). It is `None` by default and can be hidden from API responses with `response_model_exclude_none=True`. ### [`ErrorResponse`](../reference/schemas.md#fastapi_toolsets.schemas.ErrorResponse) diff --git a/docs/reference/schemas.md b/docs/reference/schemas.md index 40abe5b..40dcb57 100644 --- a/docs/reference/schemas.md +++ b/docs/reference/schemas.md @@ -12,7 +12,8 @@ from fastapi_toolsets.schemas import ( BaseResponse, Response, ErrorResponse, - Pagination, + OffsetPagination, + CursorPagination, PaginatedResponse, ) ``` @@ -29,6 +30,8 @@ from fastapi_toolsets.schemas import ( ## ::: fastapi_toolsets.schemas.ErrorResponse -## ::: fastapi_toolsets.schemas.Pagination +## ::: fastapi_toolsets.schemas.OffsetPagination + +## ::: fastapi_toolsets.schemas.CursorPagination ## ::: fastapi_toolsets.schemas.PaginatedResponse