This page describes the conventions for documenting REST endpoints in OpenAPI/Swagger across the project.
Use @ParameterObject
@ParameterObject
When documenting Spring Data Pageable parameters, use @ParameterObject.
Pageable
@GetMapping public ResponseEntity<PageResponse<CompetitionResponse>> getAllVisible( @ParameterObject @PageableDefault(size = 20, sort = "createdAt") Pageable pageable) { ... }
This automatically documents the following query parameters:
page
size
sort
and avoids exposing Pageable as a single object in Swagger UI.
Correct Swagger rendering
Avoid
Do not manually document page, size, and sort unless additional customization is required.
@Parameters({ @Parameter(name = "page", ...), @Parameter(name = "size", ...), @Parameter(name = "sort", ...) }) @Parameter(hidden = true) Pageable pageable
Use @Parameter only when the default generated documentation is not sufficient.
@Parameter
Typical use cases include:
Example:
@Parameter( description = "Competition identifier", example = "42") @PathVariable Long id
There was an error while loading. Please reload this page.