giuseppe-trisciuoglio/developer-kit

Comprehensive developer toolkit providing reusable skills for Java/Spring Boot, TypeScript/NestJS/React/Next.js, Python, PHP, AWS CloudFormation, AI/RAG, DevOps, and more.

Quality

89%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Risky

Do not use without reviewing

Pagination Documentation

Name: giuseppe-trisciuoglio/developer-kit
Rating: 89.68656716417911 (1 reviews)
Author: giuseppe-trisciuoglio

Spring Data Pageable Support

Basic Pageable Parameter

import org.springdoc.core.annotations.ParameterObject;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

@Operation(summary = "Get paginated list of books")
@GetMapping("/paginated")
public Page<Book> findAllPaginated(
    @ParameterObject Pageable pageable
) {
    return repository.findAll(pageable);
}

This generates parameters:

page: Page number (0-based)
size: Page size
sort: Sort criteria (field,direction)

Custom Pageable Documentation

@Operation(summary = "Get paginated books with custom defaults")
@GetMapping("/paginated")
public Page<Book> getBooksPaginated(
    @ParameterObject
    @Parameter(
        description = "Pagination parameters (default: page=0, size=20, sort=id,asc)",
        example = "page=0&size=20&sort=title,asc"
    )
    Pageable pageable
) {
    return repository.findAll(pageable);
}

Pageable with `@ParameterObject`

@GetMapping("/search")
public Page<Book> searchBooks(
    @Parameter(description = "Search query")
    @RequestParam String query,

    @ParameterObject
    Pageable pageable
) {
    return repository.searchByTitle(query, pageable);
}

Custom Page Response

Page Metadata

import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageImpl;
import org.springframework.data.domain.PageRequest;

@Schema(description = "Paginated response wrapper")
public record PagedResponse<T>(
    @Schema(description = "List of items")
    List<T> content,

    @Schema(description = "Current page number (0-based)", example = "0")
    int currentPage,

    @Schema(description = "Total number of pages", example = "5")
    int totalPages,

    @Schema(description = "Total number of items", example = "100")
    long totalItems,

    @Schema(description = "Number of items per page", example = "20")
    int pageSize,

    @Schema(description = "Whether this is the first page", example = "true")
    boolean isFirst,

    @Schema(description = "Whether this is the last page", example = "false")
    boolean isLast
) {
    public static <T> PagedResponse<T> from(Page<T> page) {
        return new PagedResponse<>(
            page.getContent(),
            page.getNumber(),
            page.getTotalPages(),
            page.getTotalElements(),
            page.getSize(),
            page.isFirst(),
            page.isLast()
        );
    }
}

@Operation(summary = "Get books with custom pagination")
@GetMapping("/paged")
public PagedResponse<Book> getPagedBooks(
    @ParameterObject Pageable pageable
) {
    Page<Book> page = repository.findAll(pageable);
    return PagedResponse.from(page);
}

Slice Documentation

Using Slice for Large Datasets

import org.springframework.data.domain.Slice;

@Operation(summary = "Get books as slice (no count query)")
@GetMapping("/sliced")
public Slice<Book> getBookSlice(
    @Parameter(description = "Page number (0-based)", example = "0")
    @RequestParam(defaultValue = "0") int page,

    @Parameter(description = "Page size", example = "20")
    @RequestParam(defaultValue = "20") int size
) {
    return repository.findAll(PageRequest.of(page, size));
}

Custom Pagination Objects

Custom Pagination DTO

@Schema(description = "Pagination request")
public record PaginationRequest(
    @Schema(description = "Page number (0-based)", example = "0", minValue = "0")
    @Min(0)
    int page,

    @Schema(description = "Page size", example = "20", minValue = "1", maxValue = "100")
    @Min(1)
    @Max(100)
    int size,

    @Schema(description = "Sort field", example = "title")
    String sortField,

    @Schema(description = "Sort direction", example = "asc", allowableValues = {"asc", "desc"})
    String sortDirection
) {
    public Pageable toPageable() {
        Sort.Direction direction = Sort.Direction.fromString(sortDirection);
        return PageRequest.of(page, size, Sort.by(direction, sortField));
    }
}

@Operation(summary = "Get books with custom pagination")
@PostMapping("/paginated-custom")
public Page<Book> getBooksCustomPagination(
    @RequestBody PaginationRequest request
) {
    return repository.findAll(request.toPageable());
}

Pagination with Filters

Filtered Pageable Endpoints

@Operation(summary = "Search books with pagination and filters")
@GetMapping("/search")
public Page<Book> searchBooks(
    @Parameter(description = "Title filter")
    @RequestParam(required = false) String title,

    @Parameter(description = "Author filter")
    @RequestParam(required = false) String author,

    @Parameter(description = "Minimum price")
    @RequestParam(required = false) BigDecimal minPrice,

    @Parameter(description = "Maximum price")
    @RequestParam(required = false) BigDecimal maxPrice,

    @ParameterObject
    Pageable pageable
) {
    return repository.searchBooks(title, author, minPrice, maxPrice, pageable);
}

Pagination Best Practices

Set reasonable defaults: page=0, size=20
Limit max page size: Prevent performance issues (max 100)
Document sort options: List sortable fields in description
Use Slice for large datasets: Avoid expensive count queries
Include pagination metadata: Help clients navigate results
Consider cursor-based pagination: For infinite scroll scenarios

@Operation(
    summary = "Get paginated books",
    description = """
    Returns paginated list of books.

    **Parameters:**
    - `page`: Page number (0-based, default: 0)
    - `size`: Items per page (1-100, default: 20)
    - `sort`: Sort field and direction (e.g., `title,asc` or `price,desc`)

    **Sortable fields:** id, title, author, price, publicationDate
    """
)
@GetMapping("/paginated")
public Page<Book> getPaginatedBooks(
    @ParameterObject
    @Parameter(description = "Pagination and sorting parameters")
    Pageable pageable
) {
    return repository.findAll(pageable);
}