add x-operation-extra-annotation

Author: Picazsoo

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

@@ -483,6 +483,7 @@ public void processOpts() {
         // 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");
         }
@@ -924,16 +925,17 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
 
         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"))) {
-                // 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);
+
 
                 if (hasParamsForPageable) {
                     // Automatically add x-spring-paginated to the operation
@@ -962,7 +964,8 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
                     codegenOperation.imports.add("ApiIgnore");
                 }
                 if (DocumentationProvider.SPRINGDOC.equals(getDocumentationProvider())) {
-                    codegenOperation.imports.add("ParameterObject");
+                    codegenOperation.imports.add("PageableAsQueryParam");
+                    codegenOperation.vendorExtensions.put("x-operation-extra-annotation", "@PageableAsQueryParam");
                 }
 
                 // #8315 Remove matching Spring Data Web default query params if 'x-spring-paginated' with Pageable is used

modules/openapi-generator/src/main/resources/kotlin-spring/api.mustache

@@ -84,6 +84,9 @@ class {{classname}}Controller({{#serviceInterface}}@Autowired(required = true) v
         authorizations = [{{#authMethods}}Authorization(value = "{{name}}"{{#isOAuth}}, scopes = [{{#scopes}}AuthorizationScope(scope = "{{scope}}", description = "{{description}}"){{^-last}}, {{/-last}}{{/scopes}}]{{/isOAuth}}){{^-last}}, {{/-last}}{{/authMethods}}]{{/hasAuthMethods}})
     @ApiResponses(
         value = [{{#responses}}ApiResponse(code = {{{code}}}, message = "{{{message}}}"{{#baseType}}, response = {{{.}}}::class{{/baseType}}{{#containerType}}, responseContainer = "{{{.}}}"{{/containerType}}){{^-last}},{{/-last}}{{/responses}}]){{/swagger1AnnotationLibrary}}
+    {{#vendorExtensions.x-operation-extra-annotation}}
+    {{{.}}}
+    {{/vendorExtensions.x-operation-extra-annotation}}
     @RequestMapping(
         method = [RequestMethod.{{httpMethod}}],
         // "{{#lambdaEscapeInNormalString}}{{{path}}}{{/lambdaEscapeInNormalString}}"

modules/openapi-generator/src/main/resources/kotlin-spring/apiInterface.mustache

@@ -99,6 +99,9 @@ interface {{classname}} {
     @ApiResponses(
         value = [{{#responses}}ApiResponse(code = {{{code}}}, message = "{{{message}}}"{{#baseType}}, response = {{{.}}}::class{{/baseType}}{{#containerType}}, responseContainer = "{{{.}}}"{{/containerType}}){{^-last}}, {{/-last}}{{/responses}}]
     ){{/swagger1AnnotationLibrary}}
+    {{#vendorExtensions.x-operation-extra-annotation}}
+    {{{.}}}
+    {{/vendorExtensions.x-operation-extra-annotation}}
     @RequestMapping(
         method = [RequestMethod.{{httpMethod}}],
         // "{{#lambdaEscapeInNormalString}}{{{path}}}{{/lambdaEscapeInNormalString}}"

modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java

@@ -3678,7 +3678,6 @@ public void springPaginatedWithSpringDoc() throws Exception {
 
         File petApi = files.get("PetApi.kt");
         assertFileContains(petApi.toPath(), "import org.springframework.data.domain.Pageable");
-        assertFileContains(petApi.toPath(), "import org.springdoc.api.annotations.ParameterObject");
         assertFileContains(petApi.toPath(), "pageable: Pageable");
         assertFileContains(petApi.toPath(), "@Parameter(hidden = true) pageable: Pageable");
     }
@@ -3696,7 +3695,6 @@ public void springPaginatedWithSpringDocAndSpringBoot3() throws Exception {
 
         File petApi = files.get("PetApi.kt");
         assertFileContains(petApi.toPath(), "import org.springframework.data.domain.Pageable");
-        assertFileContains(petApi.toPath(), "import org.springdoc.core.annotations.ParameterObject");
         assertFileContains(petApi.toPath(), "pageable: Pageable");
     }
 
@@ -3862,6 +3860,49 @@ public void springPaginatedWithSwagger1AnnotationLibrary() throws Exception {
         assertFileContains(petApi.toPath(), "@ApiParam(hidden = true) pageable: Pageable");
     }
 
+    @Test
+    public void springPaginatedWithSpringDocUsesPageableAsQueryParam() throws Exception {
+        Map<String, Object> additionalProperties = new HashMap<>();
+        additionalProperties.put(USE_TAGS, "true");
+        additionalProperties.put(DOCUMENTATION_PROVIDER, "springdoc");
+        additionalProperties.put(INTERFACE_ONLY, "true");
+        additionalProperties.put(SKIP_DEFAULT_INTERFACE, "true");
+
+        Map<String, File> files = generateFromContract("src/test/resources/3_0/spring/petstore-with-spring-pageable.yaml", additionalProperties);
+
+        File petApi = files.get("PetApi.kt");
+        String content = Files.readString(petApi.toPath());
+
+        // Verify @PageableAsQueryParam annotation is present at method level
+        assertFileContains(petApi.toPath(), "import org.springdoc.core.converters.models.PageableAsQueryParam");
+        assertFileContains(petApi.toPath(), "@PageableAsQueryParam");
+
+        // Verify Pageable parameter has @Parameter(hidden = true)
+        assertFileContains(petApi.toPath(), "@Parameter(hidden = true) pageable: Pageable");
+
+        // Verify the annotation appears before @RequestMapping for findPetsByStatus
+        int findPetsByStatusStart = content.indexOf("fun findPetsByStatus(");
+        Assert.assertTrue(findPetsByStatusStart > 0, "findPetsByStatus method should exist");
+
+        String methodBlock = content.substring(Math.max(0, findPetsByStatusStart - 1000), findPetsByStatusStart);
+        int pageableAsQueryParamPos = methodBlock.lastIndexOf("@PageableAsQueryParam");
+        int requestMappingPos = methodBlock.lastIndexOf("@RequestMapping");
+
+        Assert.assertTrue(pageableAsQueryParamPos > 0, "@PageableAsQueryParam should be present before method");
+        Assert.assertTrue(requestMappingPos > pageableAsQueryParamPos,
+            "@PageableAsQueryParam should appear before @RequestMapping");
+
+        // Verify page, size, sort parameters are NOT in the method signature
+        String methodSignature = content.substring(findPetsByStatusStart,
+            content.indexOf("): ResponseEntity", findPetsByStatusStart));
+        Assert.assertFalse(methodSignature.contains("page:"),
+            "page parameter should be removed from method signature");
+        Assert.assertFalse(methodSignature.contains("size:") && methodSignature.contains("@RequestParam"),
+            "size query parameter should be removed from method signature");
+        Assert.assertFalse(methodSignature.contains("sort:"),
+            "sort parameter should be removed from method signature");
+    }
+
     @Test
     public void springPaginatedNoParamsNoContext() throws Exception {
         Map<String, Object> additionalProperties = new HashMap<>();