[Java][Spring] remove 'size', 'page' and 'sort' query params if using 'x-spring-paginated' (#8315) (#21016)

* [Java][Spring] remove 'size', 'page' and 'sort' query params if using 'x-spring-paginated' (#8315)

* Properly implement samples, fixing build issues

---------

Co-authored-by: Tobias Fischer <t.fischer@goldflam.de>

Author: 30p87

docs/generators/java-camel.md

@@ -127,7 +127,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |x-class-extra-annotation|List of custom annotations to be added to model|MODEL|null
 |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-spring-paginated|Add org.springframework.data.domain.Pageable to controller method. Can be used to handle page & size query parameters|OPERATION|false
+|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
 |x-version-param|Marker property that tells that this parameter would be used for endpoint versioning. Applicable for headers & query params. true/false|OPERATION_PARAMETER|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
 

docs/generators/spring.md

@@ -120,7 +120,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |x-class-extra-annotation|List of custom annotations to be added to model|MODEL|null
 |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-spring-paginated|Add org.springframework.data.domain.Pageable to controller method. Can be used to handle page & size query parameters|OPERATION|false
+|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
 |x-version-param|Marker property that tells that this parameter would be used for endpoint versioning. Applicable for headers & query params. true/false|OPERATION_PARAMETER|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
 

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

@@ -10,7 +10,7 @@
 public enum VendorExtension {
 
     X_IMPLEMENTS("x-implements", ExtensionLevel.MODEL, "Ability to specify interfaces that model must implements", "empty array"),
-    X_SPRING_PAGINATED("x-spring-paginated", ExtensionLevel.OPERATION, "Add org.springframework.data.domain.Pageable to controller method. Can be used to handle page & size query parameters", "false"),
+    X_SPRING_PAGINATED("x-spring-paginated", ExtensionLevel.OPERATION, "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.", "false"),
     X_SPRING_PROVIDE_ARGS("x-spring-provide-args", ExtensionLevel.OPERATION, "Allows adding additional hidden parameters in the API specification to allow access to content such as header values or properties", "empty array"),
     X_DISCRIMINATOR_VALUE("x-discriminator-value", ExtensionLevel.MODEL, "Used with model inheritance to specify value for discriminator that identifies current model", ""),
     X_SETTER_EXTRA_ANNOTATION("x-setter-extra-annotation", ExtensionLevel.FIELD, "Custom annotation that can be specified over java setter for specific field", "When field is array & uniqueItems, then this extension is used to add `@JsonDeserialize(as = LinkedHashSet.class)` over setter, otherwise no value"),

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

@@ -996,6 +996,8 @@ protected boolean isConstructorWithAllArgsAllowed(CodegenModel codegenModel) {
      * Add dynamic imports based on the parameters and vendor extensions of an operation.
      * The imports are expanded by the mustache {{import}} tag available to model and api
      * templates.
+     *
+     * #8315 Also handles removing 'size', 'page' and 'sort' query parameters if using 'x-spring-paginated'.
      */
     @Override
     public CodegenOperation fromOperation(String path, String httpMethod, Operation operation, List<Server> servers) {
@@ -1023,6 +1025,15 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
             if (DocumentationProvider.SPRINGDOC.equals(getDocumentationProvider())) {
                 codegenOperation.imports.add("ParameterObject");
             }
+
+            // #8315 Spring Data Web default query params recognized by Pageable
+            List<String> defaultPageableQueryParams = new ArrayList<>(
+                Arrays.asList("page", "size", "sort")
+            );
+
+            // #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));
         }
         if (codegenOperation.vendorExtensions.containsKey("x-spring-provide-args") && !provideArgsClassSet.isEmpty()) {
             codegenOperation.imports.addAll(provideArgsClassSet);

modules/openapi-generator/src/test/resources/2_0/petstore-with-fake-endpoints-models-for-testing-with-spring-pageable.yaml

@@ -137,6 +137,31 @@ paths:
           items:
             type: string
           collectionFormat: csv
+        - name: size
+          in: header
+          description: 'A test HeaderParam for issue #8315 - must NOT be removed when x-spring-paginated:true is used.'
+          required: false
+          type: string
+        - name: size
+          in: query
+          description: 'The number of items to return per page. Test QueryParam for issue #8315 - must be removed when x-spring-paginated:true is used.'
+          required: true
+          type: integer
+          minimum: 1
+          default: 20
+        - name: page
+          in: query
+          description: 'The page to return, starting with page 0. Test QueryParam for issue #8315 - must be removed when x-spring-paginated:true is used.'
+          required: true
+          type: integer
+          minimum: 0
+          default: 0
+        - name: sort
+          in: query
+          description: 'The sorting to apply to the Pageable object. Test QueryParam for issue #8315 - must be removed when x-spring-paginated:true is used.'
+          required: true
+          type: string
+          default: id,asc
       responses:
         '200':
           description: successful operation

modules/openapi-generator/src/test/resources/2_0/petstore-with-spring-pageable.yaml

@@ -133,6 +133,31 @@ paths:
           items:
             type: string
           collectionFormat: csv
+        - name: size
+          in: header
+          description: 'A test HeaderParam for issue #8315 - must NOT be removed when x-spring-paginated:true is used.'
+          required: false
+          type: string
+        - name: size
+          in: query
+          description: 'The number of items to return per page. Test QueryParam for issue #8315 - must be removed when x-spring-paginated:true is used.'
+          required: true
+          type: integer
+          minimum: 1
+          default: 20
+        - name: page
+          in: query
+          description: 'The page to return, starting with page 0. Test QueryParam for issue #8315 - must be removed when x-spring-paginated:true is used.'
+          required: true
+          type: integer
+          minimum: 0
+          default: 0
+        - name: sort
+          in: query
+          description: 'The sorting to apply to the Pageable object. Test QueryParam for issue #8315 - must be removed when x-spring-paginated:true is used.'
+          required: true
+          type: string
+          default: id,asc
       responses:
         '200':
           description: successful operation

modules/openapi-generator/src/test/resources/3_0/spring/petstore-with-fake-endpoints-models-for-testing-with-spring-pageable.yaml

@@ -171,6 +171,38 @@ paths:
           type: array
           items:
             type: string
+      - description: "A test HeaderParam for issue #8315 - must NOT be removed when\
+          \ x-spring-paginated:true is used."
+        in: header
+        name: size
+        schema:
+          type: string
+      - description: "The number of items to return per page. Test QueryParam for\
+          \ issue #8315 - must be removed when x-spring-paginated:true is used."
+        in: query
+        name: size
+        required: true
+        schema:
+          default: 20
+          minimum: 1
+          type: integer
+      - description: "The page to return, starting with page 0. Test QueryParam for\
+          \ issue #8315 - must be removed when x-spring-paginated:true is used."
+        in: query
+        name: page
+        required: true
+        schema:
+          default: 0
+          minimum: 0
+          type: integer
+      - description: "The sorting to apply to the Pageable object. Test QueryParam\
+          \ for issue #8315 - must be removed when x-spring-paginated:true is used."
+        in: query
+        name: sort
+        required: true
+        schema:
+          default: "id,asc"
+          type: string
       responses:
         200:
           description: successful operation

modules/openapi-generator/src/test/resources/3_0/spring/petstore-with-spring-pageable.yaml

@@ -136,6 +136,38 @@ paths:
           type: array
           items:
             type: string
+      - description: "A test HeaderParam for issue #8315 - must NOT be removed when\
+          \ x-spring-paginated:true is used."
+        in: header
+        name: size
+        schema:
+          type: string
+      - description: "The number of items to return per page. Test QueryParam for\
+          \ issue #8315 - must be removed when x-spring-paginated:true is used."
+        in: query
+        name: size
+        required: true
+        schema:
+          default: 20
+          minimum: 1
+          type: integer
+      - description: "The page to return, starting with page 0. Test QueryParam for\
+          \ issue #8315 - must be removed when x-spring-paginated:true is used."
+        in: query
+        name: page
+        required: true
+        schema:
+          default: 0
+          minimum: 0
+          type: integer
+      - description: "The sorting to apply to the Pageable object. Test QueryParam\
+          \ for issue #8315 - must be removed when x-spring-paginated:true is used."
+        in: query
+        name: sort
+        required: true
+        schema:
+          default: "id,asc"
+          type: string
       responses:
         200:
           description: successful operation

samples/client/petstore/spring-cloud-spring-pageable/src/main/java/org/openapitools/api/PetApi.java

@@ -135,6 +135,7 @@ ResponseEntity<List<Pet>> findPetsByStatus(
      * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
      *
      * @param tags Tags to filter by (required)
+     * @param size A test HeaderParam for issue #8315 - must NOT be removed when x-spring-paginated:true is used. (optional)
      * @return successful operation (status code 200)
      *         or Invalid tag value (status code 400)
      * @deprecated
@@ -165,6 +166,7 @@ ResponseEntity<List<Pet>> findPetsByStatus(
     )
     ResponseEntity<List<Pet>> findPetsByTags(
         @NotNull @ApiParam(value = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags,
+        @ApiParam(value = "A test HeaderParam for issue #8315 - must NOT be removed when x-spring-paginated:true is used.") @RequestHeader(value = "size", required = false) String size,
         @ApiIgnore final Pageable pageable
     );
 

samples/openapi3/client/petstore/spring-cloud-spring-pageable/src/main/java/org/openapitools/api/PetApi.java

@@ -138,6 +138,7 @@ ResponseEntity<List<Pet>> findPetsByStatus(
      * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
      *
      * @param tags Tags to filter by (required)
+     * @param size A test HeaderParam for issue #8315 - must NOT be removed when x-spring-paginated:true is used. (optional)
      * @return successful operation (status code 200)
      *         or Invalid tag value (status code 400)
      * @deprecated
@@ -168,6 +169,7 @@ ResponseEntity<List<Pet>> findPetsByStatus(
 
     ResponseEntity<List<Pet>> findPetsByTags(
         @NotNull @Parameter(name = "tags", description = "Tags to filter by", required = true, in = ParameterIn.QUERY) @Valid @RequestParam(value = "tags", required = true) List<String> tags,
+        @Parameter(name = "size", description = "A test HeaderParam for issue #8315 - must NOT be removed when x-spring-paginated:true is used.", in = ParameterIn.HEADER) @RequestHeader(value = "size", required = false) String size,
         @ParameterObject final Pageable pageable
     );