[SPRING;KOTLIN-SPRING] fix: shift 1-based page default/bounds to Spring's 0-based page index

Merged
SE
7d ago
+175-3

Fixes #25160

Since #23575 the Spring and Kotlin-Spring generators copy the spec's page default into @PageableDefault(page = ...), and its minimum/maximum into @ValidPageable(minPage/maxPage = ...). Both of those are 0-based in Spring Data, whatever spring.data.web.pageable.one-indexed-parameters is set to: the annotation default is used as-is when page is missing, and Pageable#getPageNumber() is always 0-based. A 1-based API (minimum: 1, default: 1) therefore gets @PageableDefault(page = 1), and a request without page returns the second page. With generatePageableConstraintValidation, it also gets @ValidPageable(minPage = 1), which rejects the first page.

A page parameter with an inclusive minimum of 1 can only describe a 1-based API, because with 0-based paging it would forbid the first page. So for that case the page default and the page min/max are shifted down by one. The default is clamped at 0. Specs with minimum: 0 or no minimum are unchanged. For the spec in the issue, both generators now produce @PageableDefault(page = 0, size = 20), and with constraint validation @ValidPageable(maxPage = 99, minSize = 1, minPage = 0) for maximum: 100.

If you'd rather have an explicit option (e.g. mirroring Spring's oneIndexedParameters) than infer this from minimum, I can switch to that.

Verification done:

  • New tests in SpringPageableScanUtilsTest cover a 1-based default, a 1-based default through a $ref schema, a minimum: 1, default: 0 clamp, an unchanged 0-based default, and shifted 1-based bounds. Three of them fail without the change. SpringPageableScanUtilsTest passes 48/48.
  • SpringCodegenTest (385) and kotlin.spring.KotlinSpringServerCodegenTest (298) pass on JDK 21.
  • Regenerated bin/configs/spring*, kotlin-spring* and java-camel* (109 configs): no sample diff. No options changed, so no docs diff.
  • Generated spring and kotlin-spring from the issue's spec with the built CLI and checked the annotations above.

PR checklist

  • Read the contribution guidelines.
  • Ran the build/tests for modules/openapi-generator, regenerated the affected Spring/Kotlin-Spring samples (no changes).
  • @mention technical committee — deferring to maintainers.

Summary by cubic

Fixes #25160 by shifting 1-based page defaults and min/max bounds to Spring's 0-based page index, so a request without page no longer returns the second page and page 1 is not rejected.

  • Only specs with an inclusive page.minimum of exactly 1 are treated as 1-based; their default and bounds are decremented by one, with the default clamped at 0. Other minimums, exclusive minimums, and no minimum are unchanged.
  • Adds tests covering 1-based defaults (including via $ref), clamping, and shifted bounds.