[JAVA-SPRING;KOTLIN-SPRING] improvement: Allow autoXSpringPaginated for endpoints without sort

[Picazsoo]

Change autoXSpringPaginated from a boolean switch into a string-enum option with three canonical values:

• none: disable auto-detection (default)
• page-size-sort: require page, size, and sort query parameters (identical to the previous true behavior)
• page-size: require only page and size; sort may be absent (new)

The legacy true/false values are still accepted as deprecated aliases for page-size-sort/none respectively. A deprecation warning is logged once via the generator logger only when the option is explicitly set to true/false; leaving the option unset keeps the silent none default with no warning.

• Add SpringPageableScanUtils.AutoPaginationMode enum and resolveAutoPaginationMode() to centralize parsing/validation/deprecation warnings shared by SpringCodegen and KotlinSpringServerCodegen.
• Update willBePageable, applyAutoXSpringPaginatedIfNeeded, and the scanSortValidationEnums/scanPageableDefaults/scanPageableConstraints/ scanAll methods to take AutoPaginationMode instead of boolean.
• Replace the boolean CLI switch with a documented string-enum CLI option in SpringCodegen and KotlinSpringServerCodegen (JavaCamelServerCodegen inherits the behavior since it extends SpringCodegen).
• Update existing tests to use the new enum where internal signatures changed; add new tests for page-size mode detection, deprecation warnings (once when explicit, never when unset), and invalid values.
• Regenerate docs/generators/{spring,kotlin-spring,java-camel}.md.

PR checklist

• Read the contribution guidelines.
• 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.
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

---

Summary by cubic

Changes autoXSpringPaginated from a boolean switch into a string-enum option so Spring generators can auto-detect Pageable endpoints that have only page and size (no sort). Previously auto-detection required all three parameters; now page-size mode is available, and the default none disables auto-detection.

• Accepts canonical values none, page-size-sort, and page-size; page-size-sort matches the old true behavior.
• Legacy true/false values still work but log a deprecation warning when explicitly set; the unset default stays silent.
• Parsing and validation are centralized in SpringPageableScanUtils and shared by SpringCodegen, KotlinSpringServerCodegen, and JavaCamelServerCodegen.
• Adds tests for page-size detection, deprecation warnings, and invalid values; regenerates generator docs.

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

[cubic-dev-ai]

5 issues found across 9 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java">

<violation number="1" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java:179">
P2: This removes the public `setAutoXSpringPaginated(boolean)` API without exposing a replacement setter for the string mode. Add a setter that resolves and updates both `autoXSpringPaginated` and `autoXSpringPaginatedMode`, retaining a deprecated boolean overload if compatibility is required.</violation>

<violation number="2" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java:179">
P3: Kotlin now always writes a String `autoXSpringPaginated="none"` back into `additionalProperties`, unconditional on `isPageableSupported()` and even when the option was unset, while the parallel Spring change only writes back inside the `containsKey` guard. This leaves the two generators' `additionalProperties` inconsistent (Kotlin always carries the key, Spring omits it when unset, and the type changed from boolean to String). Guard the write-back the same way as Spring so the property is only emitted when it was actually configured.</violation>
</file>

<file name="modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java">

<violation number="1" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java:205">
P2: Programmatic callers can no longer use the public `setAutoXSpringPaginated(boolean)` generated by the removed `@Setter`, despite the legacy boolean aliases being retained. Preserve a compatibility setter that routes the boolean value into the new mode/configuration path, and provide a String setter for the new option.</violation>
</file>

<file name="modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java">

<violation number="1" location="modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java:5427">
P2: These tests cast the SLF4J logger to ch.qos.logback.classic.Logger, which only works when logback is the active binding. The test classpath also carries slf4j-simple as a second binding (declared later in pom.xml), so selection depends on classpath ordering; a different ordering (IDE, custom runner) makes the cast throw ClassCastException and both deprecation tests fail. Pin the binding (e.g., make slf4j-simple test-excluded or scope it out of the test classpath) so logback is the sole provider before relying on the cast.</violation>
</file>

<file name="modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringPageableScanUtils.java">

<violation number="1" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringPageableScanUtils.java:237">
P3: Changing `scanAll` to accept `AutoPaginationMode` leaves the class-level Javadoc link pointing to a nonexistent boolean overload, producing a broken API-doc reference. Update the link to the enum signature.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: This removes the public setAutoXSpringPaginated(boolean) API without exposing a replacement setter for the string mode. Add a setter that resolves and updates both autoXSpringPaginated and autoXSpringPaginatedMode, retaining a deprecated boolean overload if compatibility is required.

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/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java, line 179:

<comment>This removes the public `setAutoXSpringPaginated(boolean)` API without exposing a replacement setter for the string mode. Add a setter that resolves and updates both `autoXSpringPaginated` and `autoXSpringPaginatedMode`, retaining a deprecated boolean overload if compatibility is required.</comment>

<file context>
@@ -176,7 +176,8 @@ public enum RequestMappingMode {
     @Setter private DeclarativeInterfaceReactiveMode declarativeInterfaceReactiveMode = DeclarativeInterfaceReactiveMode.coroutines;
     @Setter private boolean useResponseEntity = true;
-    @Setter private boolean autoXSpringPaginated = false;
+    @Getter private String autoXSpringPaginated = SpringPageableScanUtils.AUTO_PAGINATION_MODE_NONE;
+    @Getter private SpringPageableScanUtils.AutoPaginationMode autoXSpringPaginatedMode = SpringPageableScanUtils.AutoPaginationMode.NONE;
     @Setter private boolean generateSortValidation = false;
</file context>

[cubic-dev-ai]

P2: Programmatic callers can no longer use the public setAutoXSpringPaginated(boolean) generated by the removed @Setter, despite the legacy boolean aliases being retained. Preserve a compatibility setter that routes the boolean value into the new mode/configuration path, and provide a String setter for the new option.

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/java/org/openapitools/codegen/languages/SpringCodegen.java, line 205:

<comment>Programmatic callers can no longer use the public `setAutoXSpringPaginated(boolean)` generated by the removed `@Setter`, despite the legacy boolean aliases being retained. Preserve a compatibility setter that routes the boolean value into the new mode/configuration path, and provide a String setter for the new option.</comment>

<file context>
@@ -202,7 +202,8 @@ public enum RequestMappingMode {
     protected boolean additionalNotNullAnnotations = false;
     @Setter boolean useHttpServiceProxyFactoryInterfacesConfigurator = false;
-    @Setter protected boolean autoXSpringPaginated = false;
+    @Getter protected String autoXSpringPaginated = SpringPageableScanUtils.AUTO_PAGINATION_MODE_NONE;
+    @Getter private SpringPageableScanUtils.AutoPaginationMode autoXSpringPaginatedMode = SpringPageableScanUtils.AutoPaginationMode.NONE;
     @Setter protected boolean generateSortValidation = false;
</file context>

[cubic-dev-ai]

P2: These tests cast the SLF4J logger to ch.qos.logback.classic.Logger, which only works when logback is the active binding. The test classpath also carries slf4j-simple as a second binding (declared later in pom.xml), so selection depends on classpath ordering; a different ordering (IDE, custom runner) makes the cast throw ClassCastException and both deprecation tests fail. Pin the binding (e.g., make slf4j-simple test-excluded or scope it out of the test classpath) so logback is the sole provider before relying on the cast.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java, line 5427:

<comment>These tests cast the SLF4J logger to ch.qos.logback.classic.Logger, which only works when logback is the active binding. The test classpath also carries slf4j-simple as a second binding (declared later in pom.xml), so selection depends on classpath ordering; a different ordering (IDE, custom runner) makes the cast throw ClassCastException and both deprecation tests fail. Pin the binding (e.g., make slf4j-simple test-excluded or scope it out of the test classpath) so logback is the sole provider before relying on the cast.</comment>

<file context>
@@ -5396,6 +5396,90 @@ public void autoXSpringPaginatedNoParamsDoesNotDetect() throws Exception {
+    @Test
+    public void autoXSpringPaginatedLegacyTrue_logsDeprecationWarningOnce() throws Exception {
+        ch.qos.logback.classic.Logger kotlinSpringLogger =
+                (ch.qos.logback.classic.Logger) org.slf4j.LoggerFactory.getLogger(KotlinSpringServerCodegen.class);
+        ch.qos.logback.core.read.ListAppender<ch.qos.logback.classic.spi.ILoggingEvent> listAppender =
+                new ch.qos.logback.core.read.ListAppender<>();
</file context>

[cubic-dev-ai]

P3: Changing scanAll to accept AutoPaginationMode leaves the class-level Javadoc link pointing to a nonexistent boolean overload, producing a broken API-doc reference. Update the link to the enum signature.

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/java/org/openapitools/codegen/languages/SpringPageableScanUtils.java, line 237:

<comment>Changing `scanAll` to accept `AutoPaginationMode` leaves the class-level Javadoc link pointing to a nonexistent boolean overload, producing a broken API-doc reference. Update the link to the enum signature.</comment>

<file context>
@@ -144,18 +232,18 @@ public boolean hasAny() {
-        sortValidationEnums = scanSortValidationEnums(openAPI, autoXSpringPaginated);
-        pageableDefaultsRegistry = scanPageableDefaults(openAPI, autoXSpringPaginated);
-        pageableConstraintsRegistry = scanPageableConstraints(openAPI, autoXSpringPaginated);
+    public void scanAll(OpenAPI openAPI, AutoPaginationMode autoPaginationMode) {
+        sortValidationEnums = scanSortValidationEnums(openAPI, autoPaginationMode);
+        pageableDefaultsRegistry = scanPageableDefaults(openAPI, autoPaginationMode);
</file context>

[cubic-dev-ai]

P3: Kotlin now always writes a String autoXSpringPaginated="none" back into additionalProperties, unconditional on isPageableSupported() and even when the option was unset, while the parallel Spring change only writes back inside the containsKey guard. This leaves the two generators' additionalProperties inconsistent (Kotlin always carries the key, Spring omits it when unset, and the type changed from boolean to String). Guard the write-back the same way as Spring so the property is only emitted when it was actually configured.

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/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java, line 179:

<comment>Kotlin now always writes a String `autoXSpringPaginated="none"` back into `additionalProperties`, unconditional on `isPageableSupported()` and even when the option was unset, while the parallel Spring change only writes back inside the `containsKey` guard. This leaves the two generators' `additionalProperties` inconsistent (Kotlin always carries the key, Spring omits it when unset, and the type changed from boolean to String). Guard the write-back the same way as Spring so the property is only emitted when it was actually configured.</comment>

<file context>
@@ -176,7 +176,8 @@ public enum RequestMappingMode {
     @Setter private DeclarativeInterfaceReactiveMode declarativeInterfaceReactiveMode = DeclarativeInterfaceReactiveMode.coroutines;
     @Setter private boolean useResponseEntity = true;
-    @Setter private boolean autoXSpringPaginated = false;
+    @Getter private String autoXSpringPaginated = SpringPageableScanUtils.AUTO_PAGINATION_MODE_NONE;
+    @Getter private SpringPageableScanUtils.AutoPaginationMode autoXSpringPaginatedMode = SpringPageableScanUtils.AutoPaginationMode.NONE;
     @Setter private boolean generateSortValidation = false;
</file context>