Merge branch 'master' into feature/add-support-for-includeHttpRequestContext-to-java-spring-codegen

Author: Picazsoo

docs/generators/kotlin-spring.md

@@ -24,6 +24,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |apiSuffix|suffix for api classes| |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|
 |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|
 |configPackage|configuration package for generated code| |org.openapitools.configuration|
@@ -73,12 +74,14 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |x-content-type|Specify custom value for 'Content-Type' header for operation|OPERATION|null
 |x-discriminator-value|Used with model inheritance to specify value for discriminator that identifies current model|MODEL|
 |x-field-extra-annotation|List of custom annotations to be added to property|FIELD, OPERATION_PARAMETER|null
+|x-operation-extra-annotation|List of custom annotations to be added to operation|OPERATION|null
 |x-pattern-message|Add this property whenever you need to customize the invalidation error message for the regex pattern of a variable|FIELD, OPERATION_PARAMETER|null
 |x-size-message|Add this property whenever you need to customize the invalidation error message for the size or length of a variable|FIELD, OPERATION_PARAMETER|null
 |x-minimum-message|Add this property whenever you need to customize the invalidation error message for the minimum value of a variable|FIELD, OPERATION_PARAMETER|null
 |x-maximum-message|Add this property whenever you need to customize the invalidation error message for the maximum value of a variable|FIELD, OPERATION_PARAMETER|null
 |x-kotlin-implements|Ability to specify interfaces that model must implement|MODEL|empty array
 |x-kotlin-implements-fields|Specify attributes that are implemented by the interface(s) added via `x-kotlin-implements`|MODEL|empty array
+|x-spring-paginated|Add `org.springframework.data.domain.Pageable` to controller method. Can be used to handle `page`, `size` and `sort` query parameters. If these query parameters are also specified in the operation spec, they will be removed from the controller method as their values can be obtained from the `Pageable` object.|OPERATION|false
 
 
 ## IMPORT MAPPING

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

@@ -45,6 +45,7 @@
 import java.net.URL;
 import java.util.*;
 import java.util.regex.Matcher;
+import java.util.stream.Collectors;
 
 import static org.openapitools.codegen.utils.CamelizeOption.LOWERCASE_FIRST_LETTER;
 import static org.openapitools.codegen.utils.StringUtils.camelize;
@@ -95,6 +96,7 @@ public class KotlinSpringServerCodegen extends AbstractKotlinCodegen
     public static final String REQUEST_MAPPING_OPTION = "requestMappingMode";
     public static final String USE_REQUEST_MAPPING_ON_CONTROLLER = "useRequestMappingOnController";
     public static final String USE_REQUEST_MAPPING_ON_INTERFACE = "useRequestMappingOnInterface";
+    public static final String AUTO_X_SPRING_PAGINATED = "autoXSpringPaginated";
 
     @Getter
     public enum DeclarativeInterfaceReactiveMode {
@@ -158,6 +160,7 @@ public String getDescription() {
     @Setter private boolean beanQualifiers = false;
     @Setter private DeclarativeInterfaceReactiveMode declarativeInterfaceReactiveMode = DeclarativeInterfaceReactiveMode.coroutines;
     @Setter private boolean useResponseEntity = true;
+    @Setter private boolean autoXSpringPaginated = false;
 
     @Getter @Setter
     protected boolean useSpringBoot3 = false;
@@ -251,6 +254,7 @@ 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);
         supportedLibraries.put(SPRING_BOOT, "Spring-boot Server application.");
         supportedLibraries.put(SPRING_CLOUD_LIBRARY,
                 "Spring-Cloud-Feign client with Spring-Boot auto-configured settings.");
@@ -447,6 +451,12 @@ public void processOpts() {
             additionalProperties.put(DOCUMENTATION_PROVIDER, DocumentationProvider.NONE);
             additionalProperties.put(ANNOTATION_LIBRARY, AnnotationLibrary.NONE);
         }
+        if (additionalProperties.containsKey(USE_SPRING_BOOT3)) {
+            this.setUseSpringBoot3(convertPropertyToBoolean(USE_SPRING_BOOT3));
+        }
+        if (additionalProperties.containsKey(INCLUDE_HTTP_REQUEST_CONTEXT)) {
+            this.setIncludeHttpRequestContext(convertPropertyToBoolean(INCLUDE_HTTP_REQUEST_CONTEXT));
+        }
 
         if (isModelMutable()) {
             typeMapping.put("array", "kotlin.collections.MutableList");
@@ -470,6 +480,14 @@ public void processOpts() {
         // used later in recursive import in postProcessingModels
         importMapping.put("com.fasterxml.jackson.annotation.JsonProperty", "com.fasterxml.jackson.annotation.JsonCreator");
 
+        // Spring-specific import mappings for x-spring-paginated support
+        importMapping.put("ApiIgnore", "springfox.documentation.annotations.ApiIgnore");
+        importMapping.put("ParameterObject", "org.springdoc.api.annotations.ParameterObject");
+        importMapping.put("PageableAsQueryParam", "org.springdoc.core.converters.models.PageableAsQueryParam");
+        if (useSpringBoot3) {
+            importMapping.put("ParameterObject", "org.springdoc.core.annotations.ParameterObject");
+        }
+
         if (!additionalProperties.containsKey(CodegenConstants.LIBRARY)) {
             additionalProperties.put(CodegenConstants.LIBRARY, library);
         }
@@ -642,13 +660,10 @@ public void processOpts() {
         if (additionalProperties.containsKey(USE_TAGS)) {
             this.setUseTags(Boolean.parseBoolean(additionalProperties.get(USE_TAGS).toString()));
         }
-
-        if (additionalProperties.containsKey(USE_SPRING_BOOT3)) {
-            this.setUseSpringBoot3(convertPropertyToBoolean(USE_SPRING_BOOT3));
-        }
-        if (additionalProperties.containsKey(INCLUDE_HTTP_REQUEST_CONTEXT)) {
-            this.setIncludeHttpRequestContext(convertPropertyToBoolean(INCLUDE_HTTP_REQUEST_CONTEXT));
+        if (additionalProperties.containsKey(AUTO_X_SPRING_PAGINATED) && library.equals(SPRING_BOOT)) {
+            this.setAutoXSpringPaginated(convertPropertyToBoolean(AUTO_X_SPRING_PAGINATED));
         }
+        writePropertyBack(AUTO_X_SPRING_PAGINATED, autoXSpringPaginated);
         if (isUseSpringBoot3()) {
             if (DocumentationProvider.SPRINGFOX.equals(getDocumentationProvider())) {
                 throw new IllegalArgumentException(DocumentationProvider.SPRINGFOX.getPropertyName() + " is not supported with Spring Boot > 3.x");
@@ -802,7 +817,7 @@ public void processOpts() {
                         gradleWrapperPackage.replace(".", File.separator), "gradle-wrapper.jar"));
             }
 
-            apiTemplateFiles.put("apiInterface.mustache", "Client.kt");
+            apiTemplateFiles.put("apiInterface.mustache", ".kt");
             apiTestTemplateFiles.clear();
         }
 
@@ -872,6 +887,108 @@ public void addOperationToGroup(String tag, String resourcePath, Operation opera
         }
     }
 
+    /**
+     * Processes operations to support the x-spring-paginated vendor extension.
+     *
+     * When x-spring-paginated is set to true on an operation, this method:
+     * - Adds org.springframework.data.domain.Pageable parameter to the method signature
+     * - Removes the default Spring Data Web pagination query parameters (page, size, sort)
+     * - Adds appropriate imports (Pageable, ApiIgnore for springfox, ParameterObject for springdoc)
+     *
+     * Auto-detection (when autoXSpringPaginated is enabled):
+     * - Automatically detects operations with 'page', 'size', and 'sort' query parameters (case-sensitive)
+     * - Applies x-spring-paginated behavior to these operations automatically
+     * - Respects manual x-spring-paginated: false setting (manual override takes precedence)
+     * - Only applies when library is spring-boot
+     *
+     * Note: x-spring-paginated is ONLY applied for server-side libraries (spring-boot).
+     * Client libraries (spring-cloud, spring-declarative-http-interface) need actual query parameters
+     * to send over HTTP, so the extension is ignored for them.
+     *
+     * Parameter ordering in generated methods:
+     * 1. Regular OpenAPI parameters (allParams)
+     * 2. Optional HttpServletRequest/ServerWebExchange (if includeHttpRequestContext is enabled)
+     * 3. Pageable parameter (if x-spring-paginated is true and library is spring-boot)
+     *
+     * This implementation mirrors the behavior in SpringCodegen for consistency.
+     *
+     * @param path the operation path
+     * @param httpMethod the HTTP method
+     * @param operation the OpenAPI operation
+     * @param servers the list of servers
+     * @return the processed CodegenOperation
+     */
+    @Override
+    public CodegenOperation fromOperation(String path, String httpMethod, Operation operation, List<io.swagger.v3.oas.models.servers.Server> servers) {
+        // #8315 Spring Data Web default query params recognized by Pageable
+        List<String> defaultPageableQueryParams = Arrays.asList("page", "size", "sort");
+
+        CodegenOperation codegenOperation = super.fromOperation(path, httpMethod, operation, servers);
+
+        // Check if operation has all three pagination query parameters (case-sensitive)
+        boolean hasParamsForPageable = codegenOperation.queryParams.stream()
+                .map(p -> p.baseName)
+                .collect(Collectors.toSet())
+                .containsAll(defaultPageableQueryParams);
+        // Auto-detect pagination parameters and add x-spring-paginated if autoXSpringPaginated is enabled
+        // Only for spring-boot library, respect manual x-spring-paginated: false setting
+        if (SPRING_BOOT.equals(library) && autoXSpringPaginated) {
+            // Check if x-spring-paginated is not explicitly set to false
+            if (operation.getExtensions() == null || !Boolean.FALSE.equals(operation.getExtensions().get("x-spring-paginated"))) {
+
+
+                if (hasParamsForPageable) {
+                    // Automatically add x-spring-paginated to the operation
+                    if (operation.getExtensions() == null) {
+                        operation.setExtensions(new HashMap<>());
+                    }
+                    operation.getExtensions().put("x-spring-paginated", Boolean.TRUE);
+                    codegenOperation.vendorExtensions.put("x-spring-paginated", Boolean.TRUE);
+                }
+            }
+        }
+
+        // Only process x-spring-paginated for server-side libraries (spring-boot)
+        // Client libraries (spring-cloud, spring-declarative-http-interface) need actual query parameters for HTTP requests
+        if (SPRING_BOOT.equals(library)) {
+            // add Pageable import only if x-spring-paginated explicitly used AND it's a server library
+            // this allows to use a custom Pageable schema without importing Spring Pageable.
+            if (operation.getExtensions() != null && Boolean.TRUE.equals(operation.getExtensions().get("x-spring-paginated"))) {
+                importMapping.putIfAbsent("Pageable", "org.springframework.data.domain.Pageable");
+            }
+
+            // add org.springframework.data.domain.Pageable import when needed (server libraries only)
+            if (operation.getExtensions() != null && Boolean.TRUE.equals(operation.getExtensions().get("x-spring-paginated"))) {
+                codegenOperation.imports.add("Pageable");
+                if (DocumentationProvider.SPRINGFOX.equals(getDocumentationProvider())) {
+                    codegenOperation.imports.add("ApiIgnore");
+                }
+                if (DocumentationProvider.SPRINGDOC.equals(getDocumentationProvider())) {
+                    codegenOperation.imports.add("PageableAsQueryParam");
+                    // Prepend @PageableAsQueryParam to existing x-operation-extra-annotation if present
+                    // Use getObjectAsStringList to properly handle both list and string formats:
+                    // - YAML list: ['@Ann1', '@Ann2'] -> List of annotations
+                    // - Single string: '@Ann1 @Ann2' -> Single-element list
+                    // - Nothing/null -> Empty list
+                    Object existingAnnotation = codegenOperation.vendorExtensions.get("x-operation-extra-annotation");
+                    List<String> annotations = DefaultCodegen.getObjectAsStringList(existingAnnotation);
+
+                    // Prepend @PageableAsQueryParam to the beginning of the list
+                    List<String> updatedAnnotations = new ArrayList<>();
+                    updatedAnnotations.add("@PageableAsQueryParam");
+                    updatedAnnotations.addAll(annotations);
+
+                    codegenOperation.vendorExtensions.put("x-operation-extra-annotation", updatedAnnotations);
+                }
+
+                // #8315 Remove matching Spring Data Web default query params if 'x-spring-paginated' with Pageable is used
+                codegenOperation.queryParams.removeIf(param -> defaultPageableQueryParams.contains(param.baseName));
+                codegenOperation.allParams.removeIf(param -> param.isQueryParam && defaultPageableQueryParams.contains(param.baseName));
+            }
+        }
+        return codegenOperation;
+    }
+
     @Override
     public void preprocessOpenAPI(OpenAPI openAPI) {
         super.preprocessOpenAPI(openAPI);
@@ -1117,12 +1234,14 @@ public List<VendorExtension> getSupportedVendorExtensions() {
         extensions.add(VendorExtension.X_CONTENT_TYPE);
         extensions.add(VendorExtension.X_DISCRIMINATOR_VALUE);
         extensions.add(VendorExtension.X_FIELD_EXTRA_ANNOTATION);
+        extensions.add(VendorExtension.X_OPERATION_EXTRA_ANNOTATION);
         extensions.add(VendorExtension.X_PATTERN_MESSAGE);
         extensions.add(VendorExtension.X_SIZE_MESSAGE);
         extensions.add(VendorExtension.X_MINIMUM_MESSAGE);
         extensions.add(VendorExtension.X_MAXIMUM_MESSAGE);
         extensions.add(VendorExtension.X_KOTLIN_IMPLEMENTS);
         extensions.add(VendorExtension.X_KOTLIN_IMPLEMENTS_FIELDS);
+        extensions.add(VendorExtension.X_SPRING_PAGINATED);
         return extensions;
     }
 

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

@@ -386,7 +386,7 @@ public String toParamName(String name) {
 
     @Override
     public String toEnumValue(String value, String datatype) {
-        // rust-server templates expect value to be in quotes
+        // rust-server templates expect value to be in quotes for Display/FromStr
         return "\"" + super.toEnumValue(value, datatype) + "\"";
     }
 
@@ -1564,6 +1564,58 @@ public void postProcessModelProperty(CodegenModel model, CodegenProperty propert
     public ModelsMap postProcessModels(ModelsMap objs) {
         ModelsMap result = super.postProcessModelsEnum(objs);
 
+        // Detect integer enums and mark them for serde_repr usage
+        for (ModelMap modelMap : result.getModels()) {
+            CodegenModel model = modelMap.getModel();
+
+            if (Boolean.TRUE.equals(model.isEnum) &&
+                (model.isInteger || model.isLong || model.isNumber) &&
+                model.allowableValues != null) {
+
+                // Determine the correct Rust type for the enum's repr
+                String rustType;
+                if (model.isNumber && !model.isInteger && !model.isLong) {
+                    // Floating point enum - use dataType or default to f64
+                    rustType = "f32".equals(model.dataType) ? "f32" : "f64";
+                } else {
+                    // Integer enum - apply the same type fitting logic as properties
+                    rustType = applyIntegerTypeFitting(
+                        model.getFormat(),
+                        model.getMinimum(),
+                        model.getMaximum(),
+                        model.getExclusiveMinimum(),
+                        model.getExclusiveMaximum());
+                    // If applyIntegerTypeFitting returns null, default to i32
+                    if (rustType == null) {
+                        rustType = "i32";
+                    }
+                }
+
+                // Mark this as an integer enum and store the Rust type
+                model.vendorExtensions.put("x-is-integer-enum", true);
+                model.vendorExtensions.put("x-rust-type", rustType);
+
+                // Set global flag to include serde_repr dependency
+                additionalProperties.put("apiUsesIntegerEnums", true);
+
+                // Add numeric discriminant values for enum variants
+                @SuppressWarnings("unchecked")
+                List<Map<String, Object>> enumVars =
+                    (List<Map<String, Object>>) model.allowableValues.get("enumVars");
+
+                if (enumVars != null) {
+                    for (Map<String, Object> enumVar : enumVars) {
+                        String value = (String) enumVar.get("value");
+                        if (value != null) {
+                            // Strip quotes to get raw numeric value
+                            String numericValue = value.substring(1, value.length() - 1);
+                            enumVar.put("numericDiscriminant", numericValue);
+                        }
+                    }
+                }
+            }
+        }
+
         // Check for model names that conflict with serde_valid macro internals
         // Once we find one, set a class-level flag that persists across all model batches
         if (!hasConflictingModelNames) {