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

[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.

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 to match Java Spring. Generates Pageable for Spring Boot servers, adds auto-detect, removes page/size/sort, applies correct annotations/imports, updates docs/samples/tests, and fixes declarative interface naming.

• New Features

  • Generates Pageable only when x-spring-paginated is true and the library is spring-boot; client generators ignore it and keep query params.
  • Adds autoXSpringPaginated for Spring Boot: when enabled, auto-detects page/size/sort and switches to Pageable unless x-spring-paginated is explicitly false.
  • Removes page, size, and sort query params; preserves non-query params with the same names (e.g., header "size").
  • Applies ParameterObject (springdoc) or ApiIgnore (springfox); Spring Boot 3 uses org.springdoc.core.annotations.
  • Keeps parameter order: OpenAPI params → request/exchange (if enabled) → pageable; works with reactive, delegate, service interface, and interface-only modes; fixes declarative interface naming (Api instead of *Client) in declarative modes.
  • Respects custom Pageable models; avoids importing Spring Pageable when a custom model exists.
  • Updates generated test template to declare Pageable when x-spring-paginated is present; expands samples and unit tests; fixes sample configs.
  • Documents the autoXSpringPaginated option in the Kotlin Spring generator docs.

• Dependencies

  • Adds spring-data-commons to Spring Boot (SB2/SB3) templates for Pageable.

^{Written for commit 14ed53c. 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.}

[cubic-dev-ai]

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.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/kotlin-spring/api.mustache, line 100:

<comment>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.</comment>

<file context>
@@ -95,7 +95,9 @@ class {{classname}}Controller({{#serviceInterface}}@Autowired(required = true) v
-        {{/hasParams}}{{#swagger1AnnotationLibrary}}@ApiParam(hidden = true) {{/swagger1AnnotationLibrary}}{{#swagger2AnnotationLibrary}}@Parameter(hidden = true) {{/swagger2AnnotationLibrary}}{{#reactive}}exchange: org.springframework.web.server.ServerWebExchange{{/reactive}}{{^reactive}}request: {{javaxPackage}}.servlet.http.HttpServletRequest{{/reactive}}{{/includeHttpRequestContext}}{{#hasParams}}
+        {{/hasParams}}{{#swagger1AnnotationLibrary}}@ApiParam(hidden = true) {{/swagger1AnnotationLibrary}}{{#swagger2AnnotationLibrary}}@Parameter(hidden = true) {{/swagger2AnnotationLibrary}}{{#reactive}}exchange: org.springframework.web.server.ServerWebExchange{{/reactive}}{{^reactive}}request: {{javaxPackage}}.servlet.http.HttpServletRequest{{/reactive}}{{/includeHttpRequestContext}}{{#vendorExtensions.x-spring-paginated}}{{#hasParams}},
+        {{/hasParams}}{{^hasParams}}{{#includeHttpRequestContext}},
+        {{/includeHttpRequestContext}}{{/hasParams}}{{#swagger1AnnotationLibrary}}@ApiParam(hidden = true) {{/swagger1AnnotationLibrary}}{{#swagger2AnnotationLibrary}}@Parameter(hidden = true) {{/swagger2AnnotationLibrary}}pageable: Pageable{{/vendorExtensions.x-spring-paginated}}{{#hasParams}}
     {{/hasParams}}): {{#useResponseEntity}}ResponseEntity<{{/useResponseEntity}}{{>returnTypes}}{{#useResponseEntity}}>{{/useResponseEntity}} {
         return {{>returnValue}}
</file context>

[Picazsoo]

I think this is not an issue.

[cubic-dev-ai]

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.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/kotlin-spring/libraries/spring-boot/buildGradle-sb3-Kts.mustache, line 35:

<comment>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.</comment>

<file context>
@@ -31,7 +31,8 @@ plugins {
 {{/reactive}}    implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
-    implementation("org.jetbrains.kotlin:kotlin-reflect"){{^reactive}}
+    implementation("org.jetbrains.kotlin:kotlin-reflect")
+        implementation("org.springframework.data:spring-data-commons"){{^reactive}}
         implementation("org.springframework.boot:spring-boot-starter-web"){{/reactive}}{{#reactive}}
         implementation("org.springframework.boot:spring-boot-starter-webflux")
</file context>

[Picazsoo]

this is not true - the implementation("org.springframework.data:spring-data-commons") is defined in a common shared block that is included regardless whether the project is reactive or blocking

[Picazsoo]

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