Skip to content

OpenAPI Documentation

Anton Pampukha edited this page Jul 22, 2026 · 1 revision

Overview

This page describes the conventions for documenting REST endpoints in OpenAPI/Swagger across the project.

Pageable

Use @ParameterObject

When documenting Spring Data Pageable parameters, use @ParameterObject.

@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

image

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

Custom Parameters

Use @Parameter only when the default generated documentation is not sufficient.

Typical use cases include:

  • custom descriptions;
  • custom examples;
  • custom parameter names;
  • documenting parameters that cannot be generated automatically.

Example:

@Parameter(
    description = "Competition identifier",
    example = "42")
@PathVariable Long id

Clone this wiki locally