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

docs/generators/java-camel.md

@@ -31,7 +31,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |artifactUrl|artifact URL in generated pom.xml| |https://github.com/openapitools/openapi-generator|
 |artifactVersion|artifact version in generated pom.xml. This also becomes part of the generated library's filename. If not provided, uses the version from the OpenAPI specification file. If that's also not present, uses the default value of the artifactVersion option.| |1.0.0|
 |async|use async Callable controllers| |false|
-|autoXSpringPaginated|Automatically add x-spring-paginated to operations that have 'page', 'size', and 'sort' query parameters. When enabled, operations with all three parameters will have Pageable support automatically applied. Operations with x-spring-paginated explicitly set to false will not be auto-detected. Only applies when library is spring-boot or spring-cloud.| |false|
+|autoXSpringPaginated|Automatically add x-spring-paginated to operations that have the given set of pagination query parameters. 'page-size-sort' requires 'page', 'size', and 'sort'; 'page-size' requires only 'page' and 'size' (sort may be absent). Operations with x-spring-paginated explicitly set to false will not be auto-detected. Only applies when library is spring-boot or spring-cloud. The legacy values 'true' (alias for 'page-size-sort') and 'false' (alias for 'none') are deprecated and will be removed in a future release.|<dl><dt>**none**</dt><dd>Disable auto-detection.</dd><dt>**page-size-sort**</dt><dd>Require 'page', 'size', and 'sort' query parameters.</dd><dt>**page-size**</dt><dd>Require only 'page' and 'size' query parameters.</dd><dt>**true**</dt><dd>(deprecated) alias for 'page-size-sort'.</dd><dt>**false**</dt><dd>(deprecated) alias for 'none'.</dd></dl>|none|
 |basePackage|base package (invokerPackage) for generated code| |org.openapitools|
 |bigDecimalAsString|Treat BigDecimal values as Strings to avoid precision loss.| |false|
 |booleanGetterPrefix|Set booleanGetterPrefix| |get|

docs/generators/kotlin-spring.md

@@ -24,7 +24,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |apiPackage|api package for generated code| |org.openapitools.api|
 |artifactId|Generated artifact id (name of jar).| |openapi-spring|
 |artifactVersion|Generated artifact's package version.| |1.0.0|
-|autoXSpringPaginated|Automatically add x-spring-paginated to operations that have 'page', 'size', and 'sort' query parameters. When enabled, operations with all three parameters will have Pageable support automatically applied. Operations with x-spring-paginated explicitly set to false will not be auto-detected.| |false|
+|autoXSpringPaginated|Automatically add x-spring-paginated to operations that have the given set of pagination query parameters. 'page-size-sort' requires 'page', 'size', and 'sort'; 'page-size' requires only 'page' and 'size' (sort may be absent). Operations with x-spring-paginated explicitly set to false will not be auto-detected. The legacy values 'true' (alias for 'page-size-sort') and 'false' (alias for 'none') are deprecated and will be removed in a future release.|<dl><dt>**none**</dt><dd>Disable auto-detection.</dd><dt>**page-size-sort**</dt><dd>Require 'page', 'size', and 'sort' query parameters.</dd><dt>**page-size**</dt><dd>Require only 'page' and 'size' query parameters.</dd><dt>**true**</dt><dd>(deprecated) alias for 'page-size-sort'.</dd><dt>**false**</dt><dd>(deprecated) alias for 'none'.</dd></dl>|none|
 |basePackage|base package (invokerPackage) for generated code| |org.openapitools|
 |beanQualifiers|Whether to add fully-qualifier class names as bean qualifiers in @Component and @RestController annotations. May be used to prevent bean names clash if multiple generated libraries (contexts) added to single project.| |false|
 |companionObject|Whether to generate companion objects in data classes, enabling companion extensions.| |false|

docs/generators/spring.md

@@ -31,7 +31,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |artifactUrl|artifact URL in generated pom.xml| |https://github.com/openapitools/openapi-generator|
 |artifactVersion|artifact version in generated pom.xml. This also becomes part of the generated library's filename. If not provided, uses the version from the OpenAPI specification file. If that's also not present, uses the default value of the artifactVersion option.| |1.0.0|
 |async|use async Callable controllers| |false|
-|autoXSpringPaginated|Automatically add x-spring-paginated to operations that have 'page', 'size', and 'sort' query parameters. When enabled, operations with all three parameters will have Pageable support automatically applied. Operations with x-spring-paginated explicitly set to false will not be auto-detected. Only applies when library is spring-boot or spring-cloud.| |false|
+|autoXSpringPaginated|Automatically add x-spring-paginated to operations that have the given set of pagination query parameters. 'page-size-sort' requires 'page', 'size', and 'sort'; 'page-size' requires only 'page' and 'size' (sort may be absent). Operations with x-spring-paginated explicitly set to false will not be auto-detected. Only applies when library is spring-boot or spring-cloud. The legacy values 'true' (alias for 'page-size-sort') and 'false' (alias for 'none') are deprecated and will be removed in a future release.|<dl><dt>**none**</dt><dd>Disable auto-detection.</dd><dt>**page-size-sort**</dt><dd>Require 'page', 'size', and 'sort' query parameters.</dd><dt>**page-size**</dt><dd>Require only 'page' and 'size' query parameters.</dd><dt>**true**</dt><dd>(deprecated) alias for 'page-size-sort'.</dd><dt>**false**</dt><dd>(deprecated) alias for 'none'.</dd></dl>|none|
 |basePackage|base package (invokerPackage) for generated code| |org.openapitools|
 |bigDecimalAsString|Treat BigDecimal values as Strings to avoid precision loss.| |false|
 |booleanGetterPrefix|Set booleanGetterPrefix| |get|

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java

@@ -176,7 +176,27 @@ public enum RequestMappingMode {
     @Setter private boolean beanQualifiers = false;
     @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;
+    /**
+     * Configures automatic Spring Pageable detection using a canonical mode or legacy boolean alias.
+     *
+     * @param autoXSpringPaginated the configured mode
+     */
+    public void setAutoXSpringPaginated(String autoXSpringPaginated) {
+        autoXSpringPaginatedMode = SpringPageableScanUtils.resolveAutoPaginationMode(autoXSpringPaginated);
+        this.autoXSpringPaginated = autoXSpringPaginatedMode.getCanonicalValue();
+    }
+
+    /**
+     * @deprecated Use {@link #setAutoXSpringPaginated(String)} with {@code page-size-sort} or
+     * {@code none}.
+     */
+    @Deprecated
+    public void setAutoXSpringPaginated(boolean autoXSpringPaginated) {
+        setAutoXSpringPaginated(Boolean.toString(autoXSpringPaginated));
+    }
+
     @Setter private boolean generateSortValidation = false;
     @Setter private boolean generatePageableConstraintValidation = false;
     @Setter private boolean substituteGenericPagedModel = false;
@@ -313,7 +333,13 @@ public KotlinSpringServerCodegen() {
         addOption(X_KOTLIN_IMPLEMENTS_FIELDS_SKIP, "A list of fields per schema name that should NOT be created with `override` keyword despite their presence in vendor extension `x-kotlin-implements-fields` for the schema. Example: yaml `xKotlinImplementsFieldsSkip: Pet: [photoUrls]` skips `override` for `photoUrls` in schema `Pet`", "empty map");
         addOption(SCHEMA_IMPLEMENTS, "A map of single interface or a list of interfaces per schema name that should be implemented (serves similar purpose as `x-kotlin-implements`, but is fully decoupled from the api spec). Example: yaml `schemaImplements: {Pet: com.some.pack.WithId, Category: [com.some.pack.CategoryInterface], Dog: [com.some.pack.Canine, com.some.pack.OtherInterface]}` implements interfaces in schemas `Pet` (interface `com.some.pack.WithId`), `Category` (interface `com.some.pack.CategoryInterface`), `Dog`(interfaces `com.some.pack.Canine`, `com.some.pack.OtherInterface`)", "empty map");
         addOption(SCHEMA_IMPLEMENTS_FIELDS, "A map of single field or a list of fields per schema name that should be prepended with `override` (serves similar purpose as `x-kotlin-implements-fields`, but is fully decoupled from the api spec). Example: yaml `schemaImplementsFields: {Pet: id, Category: [name, id], Dog: [bark, breed]}` marks fields to be prepended with `override` in schemas `Pet` (field `id`), `Category` (fields `name`, `id`) and `Dog` (fields `bark`, `breed`)", "empty map");
-        addSwitch(AUTO_X_SPRING_PAGINATED, "Automatically add x-spring-paginated to operations that have 'page', 'size', and 'sort' query parameters. When enabled, operations with all three parameters will have Pageable support automatically applied. Operations with x-spring-paginated explicitly set to false will not be auto-detected.", autoXSpringPaginated);
+        addOption(AUTO_X_SPRING_PAGINATED,
+                "Automatically add x-spring-paginated to operations that have the given set of pagination query "
+                + "parameters. 'page-size-sort' requires 'page', 'size', and 'sort'; 'page-size' requires only "
+                + "'page' and 'size' (sort may be absent). Operations with x-spring-paginated explicitly set to "
+                + "false will not be auto-detected. The legacy values 'true' (alias for 'page-size-sort') and "
+                + "'false' (alias for 'none') are deprecated and will be removed in a future release.",
+                autoXSpringPaginated, SpringPageableScanUtils.getAutoPaginationModeEnumValues());
         addSwitch(GENERATE_SORT_VALIDATION, "Generate a @ValidSort annotation and SortValidator class, and apply @ValidSort to the injected Pageable parameter of operations whose 'sort' parameter has enum values. The annotation validates that sort values in the Pageable object match the allowed enum values from the spec. Requires useBeanValidation=true and library is spring-boot or spring-cloud.", generateSortValidation);
         addSwitch(GENERATE_PAGEABLE_CONSTRAINT_VALIDATION, "Generate a @ValidPageable annotation and PageableConstraintValidator class, and apply @ValidPageable to the injected Pageable parameter of operations whose 'page' or 'size' parameter specifies a maximum constraint. The annotation enforces those constraints on the Pageable object that replaces the individual page/size query parameters. Requires useBeanValidation=true and library is spring-boot or spring-cloud.", generatePageableConstraintValidation);
         addSwitch(SUBSTITUTE_GENERIC_PAGED_MODEL,
@@ -830,10 +856,16 @@ public void processOpts() {
         if (additionalProperties.containsKey(USE_TAGS)) {
             this.setUseTags(Boolean.parseBoolean(additionalProperties.get(USE_TAGS).toString()));
         }
-        if (additionalProperties.containsKey(AUTO_X_SPRING_PAGINATED) && isPageableSupported()) {
-            this.setAutoXSpringPaginated(convertPropertyToBoolean(AUTO_X_SPRING_PAGINATED));
+        // Validate an explicitly supplied value for every library so typos are not silently ignored;
+        // the resolved mode is only used (and written back) when Pageable is supported.
+        if (additionalProperties.containsKey(AUTO_X_SPRING_PAGINATED)) {
+            String rawAutoXSpringPaginated = String.valueOf(additionalProperties.get(AUTO_X_SPRING_PAGINATED));
+            pageableUtils.warnIfDeprecatedAutoPaginationValue(rawAutoXSpringPaginated);
+            setAutoXSpringPaginated(rawAutoXSpringPaginated);
+            if (isPageableSupported()) {
+                writePropertyBack(AUTO_X_SPRING_PAGINATED, autoXSpringPaginated);
+            }
         }
-        writePropertyBack(AUTO_X_SPRING_PAGINATED, autoXSpringPaginated);
         if (additionalProperties.containsKey(GENERATE_SORT_VALIDATION) && isPageableSupported()) {
             this.setGenerateSortValidation(convertPropertyToBoolean(GENERATE_SORT_VALIDATION));
         }
@@ -1173,7 +1205,7 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
         // Only for libraries that support Pageable; respect manual x-spring-paginated: false override.
         if (isPageableSupported()) {
             SpringPageableScanUtils.applyAutoXSpringPaginatedIfNeeded(
-                    openAPI, operation, autoXSpringPaginated);
+                    openAPI, operation, autoXSpringPaginatedMode);
         }
 
         CodegenOperation codegenOperation = super.fromOperation(path, httpMethod, operation, servers);
@@ -1253,7 +1285,7 @@ public void preprocessOpenAPI(OpenAPI openAPI) {
         }
 
         if (isPageableSupported()) {
-            pageableUtils.scanAll(openAPI, autoXSpringPaginated);
+            pageableUtils.scanAll(openAPI, autoXSpringPaginatedMode);
 
             if (generateSortValidation && useBeanValidation && !pageableUtils.sortValidationEnums.isEmpty()) {
                 importMapping.putIfAbsent("ValidSort", configPackage + ".ValidSort");

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java

@@ -208,7 +208,27 @@ public enum RequestMappingMode {
     @Getter @Setter
     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;
+    /**
+     * Configures automatic Spring Pageable detection using a canonical mode or legacy boolean alias.
+     *
+     * @param autoXSpringPaginated the configured mode
+     */
+    public void setAutoXSpringPaginated(String autoXSpringPaginated) {
+        autoXSpringPaginatedMode = SpringPageableScanUtils.resolveAutoPaginationMode(autoXSpringPaginated);
+        this.autoXSpringPaginated = autoXSpringPaginatedMode.getCanonicalValue();
+    }
+
+    /**
+     * @deprecated Use {@link #setAutoXSpringPaginated(String)} with {@code page-size-sort} or
+     * {@code none}.
+     */
+    @Deprecated
+    public void setAutoXSpringPaginated(boolean autoXSpringPaginated) {
+        setAutoXSpringPaginated(Boolean.toString(autoXSpringPaginated));
+    }
+
     @Setter protected boolean generateSortValidation = false;
     @Setter protected boolean generatePageableConstraintValidation = false;
     @Setter protected boolean substituteGenericPagedModel = false;
@@ -409,12 +429,16 @@ public SpringCodegen() {
         cliOptions.add(CliOption.newBoolean(ADDITIONAL_NOT_NULL_ANNOTATIONS,
                 "Add @NotNull to path variables (required by default) and requestBody.",
                 additionalNotNullAnnotations));
-        cliOptions.add(CliOption.newBoolean(AUTO_X_SPRING_PAGINATED,
-                "Automatically add x-spring-paginated to operations that have 'page', 'size', and 'sort' query parameters. "
-                + "When enabled, operations with all three parameters will have Pageable support automatically applied. "
-                + "Operations with x-spring-paginated explicitly set to false will not be auto-detected. "
-                + "Only applies when library is spring-boot or spring-cloud.",
-                autoXSpringPaginated));
+        final CliOption autoXSpringPaginatedOption = new CliOption(AUTO_X_SPRING_PAGINATED,
+                "Automatically add x-spring-paginated to operations that have the given set of pagination query "
+                + "parameters. 'page-size-sort' requires 'page', 'size', and 'sort'; 'page-size' requires only "
+                + "'page' and 'size' (sort may be absent). Operations with x-spring-paginated explicitly set to "
+                + "false will not be auto-detected. Only applies when library is spring-boot or spring-cloud. "
+                + "The legacy values 'true' (alias for 'page-size-sort') and 'false' (alias for 'none') are "
+                + "deprecated and will be removed in a future release.")
+                .defaultValue(autoXSpringPaginated);
+        autoXSpringPaginatedOption.setEnum(SpringPageableScanUtils.getAutoPaginationModeEnumValues());
+        cliOptions.add(autoXSpringPaginatedOption);
         cliOptions.add(CliOption.newBoolean(GENERATE_SORT_VALIDATION,
                 "Generate a @ValidSort annotation and SortValidator class, and apply @ValidSort to "
                 + "the injected Pageable parameter of operations whose 'sort' parameter has enum values. "
@@ -694,8 +718,17 @@ public void processOpts() {
         convertPropertyToBooleanAndWriteBack(SUBSTITUTE_GENERIC_PAGED_MODEL, this::setSubstituteGenericPagedModel);
         convertPropertyToBooleanAndWriteBack(CodegenConstants.USE_ENUM_VALUE_INTERFACE, this::setUseEnumValueInterface);
 
+        // Validate an explicitly supplied value for every library so typos are not silently ignored;
+        // the resolved mode is only used (and written back) when Pageable is supported.
+        if (additionalProperties.containsKey(AUTO_X_SPRING_PAGINATED)) {
+            String rawAutoXSpringPaginated = String.valueOf(additionalProperties.get(AUTO_X_SPRING_PAGINATED));
+            pageableUtils.warnIfDeprecatedAutoPaginationValue(rawAutoXSpringPaginated);
+            setAutoXSpringPaginated(rawAutoXSpringPaginated);
+        }
         if (isPageableSupported()) {
-            convertPropertyToBooleanAndWriteBack(AUTO_X_SPRING_PAGINATED, this::setAutoXSpringPaginated);
+            if (additionalProperties.containsKey(AUTO_X_SPRING_PAGINATED)) {
+                writePropertyBack(AUTO_X_SPRING_PAGINATED, this.autoXSpringPaginated);
+            }
             convertPropertyToBooleanAndWriteBack(GENERATE_SORT_VALIDATION, this::setGenerateSortValidation);
             convertPropertyToBooleanAndWriteBack(GENERATE_PAGEABLE_CONSTRAINT_VALIDATION, this::setGeneratePageableConstraintValidation);
         }
@@ -989,7 +1022,7 @@ public void preprocessOpenAPI(OpenAPI openAPI) {
         }
 
         if (isPageableSupported()) {
-            pageableUtils.scanAll(openAPI, autoXSpringPaginated);
+            pageableUtils.scanAll(openAPI, autoXSpringPaginatedMode);
 
             if (generateSortValidation && useBeanValidation && !pageableUtils.sortValidationEnums.isEmpty()) {
                 importMapping.putIfAbsent("ValidSort", configPackage + ".ValidSort");
@@ -1480,14 +1513,14 @@ protected boolean isConstructorWithAllArgsAllowed(CodegenModel codegenModel) {
     @Override
     public CodegenOperation fromOperation(String path, String httpMethod, Operation operation, List<Server> servers) {
 
-        // Auto-detect pagination parameters and set x-spring-paginated if autoXSpringPaginated is enabled.
+        // Auto-detect pagination parameters and set x-spring-paginated if autoXSpringPaginated auto-detection is enabled.
         // Must be done BEFORE super.fromOperation() so that the base codegen populates
         // codegenOperation.vendorExtensions from the extension we just set on 'operation'.
         // Only for libraries that support Pageable (spring-boot, spring-cloud);
         // respect manual x-spring-paginated: false override.
         if (isPageableSupported()) {
             SpringPageableScanUtils.applyAutoXSpringPaginatedIfNeeded(
-                    openAPI, operation, autoXSpringPaginated);
+                    openAPI, operation, autoXSpringPaginatedMode);
         }
 
         // add Pageable import only if x-spring-paginated explicitly used AND it's a pageable-supporting library.