[KOTLIN;SPRING] - add support for 'x-spring-paginated' to get closer to feature parity with java-spring codegen; add 'autoXSpringPaginated' option; support x-operation-extra-annotation

[Picazsoo]

Summary

This PR improves pagination support in the kotlin-spring generator by aligning generated controllers with Spring Data Web conventions. fixes #19466

It introduces a new x-spring-paginated vendor extension that allows an operation to use Spring’s Pageable interface instead of separate page, size, and sort query parameters. When enabled, these query parameters are removed from the generated method signature and replaced with a single Pageable argument, resulting in cleaner and more idiomatic Spring controller APIs.

In addition, an opt-in autoXSpringPaginated configuration option is added for cases where the OpenAPI specification cannot be modified (for example, third-party APIs). When enabled, the generator automatically applies the same Pageable behavior to operations that define the standard page, size, and sort query parameters.

Both features apply only to the spring-boot server library, are fully backward compatible, and have no effect unless explicitly enabled. They work consistently across blocking and reactive modes and integrate with existing Spring documentation tooling.

important - unless you have api spec which currently contains x-spring-paginated or x-operation-extra-annotation then this will not have an impact on you and is fully backwards compatible

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• If your PR solves a reported issue, reference it using GitHub's linking syntax (e.g., having "fixes #123" present in the PR description)
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request. Tagging @karismann (2019/03) @Zomzog (2019/04) @andrewemery (2019/10) @4brunu (2019/11) @yutaka0m (2020/03) @stefankoppier (2022/06) @e5l (2024/10) @dennisameling (2026/02)

---

Summary by cubic

Adds x-spring-paginated support to Kotlin Spring and a new autoXSpringPaginated option to align with java-spring. Generates Pageable for Spring Boot servers, supports extra method annotations, removes page/size/sort, fixes declarative interface naming, and updates docs/samples/tests.

• New Features

  • Generates Pageable only when x-spring-paginated is true and the library is spring-boot; client generators keep query params.
  • Adds autoXSpringPaginated for Spring Boot to auto-detect page/size/sort and switch to Pageable unless x-spring-paginated is false.
  • Removes page, size, and sort query params; preserves non-query params with the same names; keeps OpenAPI param order → request/exchange (if enabled) → pageable; updates api_test to pass Pageable.
  • Applies springdoc/springfox annotations (ParameterObject or ApiIgnore); Spring Boot 3 uses org.springdoc.core.annotations; merges with @PageableAsQueryParam when present.
  • Supports x-operation-extra-annotation (string or list) to inject method annotations in both controller and interface templates.
  • Works across reactive, delegate, service interface, and interface-only modes; fixes declarative interface naming in declarative modes (Api instead of *Client).
  • Respects custom Pageable models; adds comprehensive tests/specs and regenerates samples and docs.

• Dependencies

  • Adds org.springframework.data:spring-data-commons to Spring Boot (SB2/SB3) templates and samples for Pageable.

^{Written for commit f6a2a8b. Summary will update on new commits.}

[cubic-dev-ai]

4 issues found across 63 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="modules/openapi-generator/src/main/resources/kotlin-spring/api.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/kotlin-spring/api.mustache:100">
P2: The Pageable parameter is added with `@Parameter(hidden = true)` but no `@ParameterObject` or explicit pagination parameters are added, so enabling x-spring-paginated will hide pagination params from generated OpenAPI docs. Springdoc expects `@ParameterObject` (or explicit query params) to expose page/size/sort; hiding the pageable without those means pagination won’t appear in the docs.</violation>
</file>

<file name="samples/server/petstore/kotlin-springboot-x-kotlin-implements/src/main/kotlin/org/openapitools/api/PetApi.kt">

<violation number="1" location="samples/server/petstore/kotlin-springboot-x-kotlin-implements/src/main/kotlin/org/openapitools/api/PetApi.kt:241">
P2: The handler declares a required @PathVariable("categoryId") but the mapped path is "/pet/paginated/mixed" without a {categoryId} placeholder, so Spring cannot bind the path variable and requests will fail.</violation>

<violation number="2" location="samples/server/petstore/kotlin-springboot-x-kotlin-implements/src/main/kotlin/org/openapitools/api/PetApi.kt:449">
P2: `listPetsByIdPaginated` declares a required `@PathVariable("petId")`, but the mapped path constant `/pet/paginated/pathOnly` has no `{petId}` template. Spring will fail to resolve the path variable at runtime; update the path to include `{petId}` or remove the parameter.</violation>
</file>

<file name="modules/openapi-generator/src/main/resources/kotlin-spring/libraries/spring-boot/buildGradle-sb3-Kts.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/kotlin-spring/libraries/spring-boot/buildGradle-sb3-Kts.mustache:35">
P2: Reactive builds can still generate Pageable parameters, but spring-data-commons is only added in the non-reactive dependency block. This leaves reactive (webflux) builds without the Pageable dependency and causes compilation failures when x-spring-paginated is used.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[Picazsoo]

This was a misunderstanding on my part when I was implementing the declarative client. The class name should definitely match the file name.