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

docs/generators/java-camel.md

@@ -112,7 +112,7 @@ 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-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|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
 
 
 ## IMPORT MAPPING

docs/generators/spring.md

@@ -105,7 +105,7 @@ 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-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|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
 
 
 ## IMPORT MAPPING

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

@@ -6,7 +6,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_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"),
     X_WEBCLIENT_BLOCKING("x-webclient-blocking", ExtensionLevel.OPERATION, "Specifies if method for specific operation should be blocking or non-blocking(ex: return `Mono<T>/Flux<T>` or `return T/List<T>/Set<T>` & execute `.block()` inside generated method)", "false"),

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

@@ -1075,6 +1075,8 @@ public Map<String, ModelsMap> postProcessAllModels(Map<String, ModelsMap> objs)
      * 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) {
@@ -1093,6 +1095,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 (reactive) {

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

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

@@ -131,6 +131,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
@@ -158,6 +159,7 @@ ResponseEntity<List<Pet>> findPetsByStatus(
     )
     ResponseEntity<List<Pet>> findPetsByTags(
         @NotNull @Parameter(name = "tags", description = "Tags to filter by", required = true) @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.") @RequestHeader(value = "size", required = false) String size,
         @ParameterObject final Pageable pageable
     );
 

samples/server/petstore/springboot-spring-pageable-delegatePattern-without-j8/src/main/java/org/openapitools/api/PetApi.java

@@ -145,6 +145,7 @@ default 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
@@ -175,9 +176,10 @@ default ResponseEntity<List<Pet>> findPetsByStatus(
     )
     default 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
     ) {
-        return getDelegate().findPetsByTags(tags, pageable);
+        return getDelegate().findPetsByTags(tags, size, pageable);
     }
 
 

samples/server/petstore/springboot-spring-pageable-delegatePattern-without-j8/src/main/java/org/openapitools/api/PetApiDelegate.java

@@ -87,13 +87,15 @@ default ResponseEntity<List<Pet>> findPetsByStatus(List<String> status, final Pa
      * 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
      * @see PetApi#findPetsByTags
      */
     @Deprecated
-    default ResponseEntity<List<Pet>> findPetsByTags(List<String> tags, final Pageable pageable) {
+    default ResponseEntity<List<Pet>> findPetsByTags(List<String> tags,
+        String size, final Pageable pageable) {
         getRequest().ifPresent(request -> {
             for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
                 if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

samples/server/petstore/springboot-spring-pageable-delegatePattern-without-j8/src/main/resources/openapi.yaml

@@ -152,6 +152,38 @@ paths:
             type: string
           type: array
         style: form
+      - 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":
           content:

samples/server/petstore/springboot-spring-pageable-delegatePattern/src/main/java/org/openapitools/api/PetApi.java

@@ -145,6 +145,7 @@ default 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
@@ -175,9 +176,10 @@ default ResponseEntity<List<Pet>> findPetsByStatus(
     )
     default 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
     ) {
-        return getDelegate().findPetsByTags(tags, pageable);
+        return getDelegate().findPetsByTags(tags, size, pageable);
     }
 
 

samples/server/petstore/springboot-spring-pageable-delegatePattern/src/main/java/org/openapitools/api/PetApiDelegate.java

@@ -87,13 +87,15 @@ default ResponseEntity<List<Pet>> findPetsByStatus(List<String> status, final Pa
      * 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
      * @see PetApi#findPetsByTags
      */
     @Deprecated
-    default ResponseEntity<List<Pet>> findPetsByTags(List<String> tags, final Pageable pageable) {
+    default ResponseEntity<List<Pet>> findPetsByTags(List<String> tags,
+        String size, final Pageable pageable) {
         getRequest().ifPresent(request -> {
             for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
                 if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

samples/server/petstore/springboot-spring-pageable-delegatePattern/src/main/resources/openapi.yaml

@@ -152,6 +152,38 @@ paths:
             type: string
           type: array
         style: form
+      - 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":
           content:

samples/server/petstore/springboot-spring-pageable-without-j8/src/main/java/org/openapitools/api/PetApi.java

@@ -166,6 +166,7 @@ default 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
@@ -196,6 +197,7 @@ default ResponseEntity<List<Pet>> findPetsByStatus(
     )
     default 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
     ) {
         getRequest().ifPresent(request -> {

samples/server/petstore/springboot-spring-pageable-without-j8/src/main/resources/openapi.yaml

@@ -152,6 +152,38 @@ paths:
             type: string
           type: array
         style: form
+      - 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":
           content:

samples/server/petstore/springboot-spring-pageable/src/main/java/org/openapitools/api/PetApi.java

@@ -166,6 +166,7 @@ default 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
@@ -196,6 +197,7 @@ default ResponseEntity<List<Pet>> findPetsByStatus(
     )
     default 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
     ) {
         getRequest().ifPresent(request -> {