feat: add validation for pageable and sort parameters with new annotations

Author: Picazsoo

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

@@ -111,6 +111,9 @@ public class SpringCodegen extends AbstractJavaCodegen
     public static final String JACKSON3_PACKAGE = "tools.jackson";
     public static final String JACKSON_PACKAGE = "jacksonPackage";
     public static final String ADDITIONAL_NOT_NULL_ANNOTATIONS = "additionalNotNullAnnotations";
+    public static final String AUTO_X_SPRING_PAGINATED = "autoXSpringPaginated";
+    public static final String GENERATE_SORT_VALIDATION = "generateSortValidation";
+    public static final String GENERATE_PAGEABLE_CONSTRAINT_VALIDATION = "generatePageableConstraintValidation";
 
     @Getter
     public enum RequestMappingMode {
@@ -186,6 +189,16 @@ public enum RequestMappingMode {
     @Getter @Setter
     protected boolean additionalNotNullAnnotations = false;
     @Setter boolean useHttpServiceProxyFactoryInterfacesConfigurator = false;
+    @Setter protected boolean autoXSpringPaginated = false;
+    @Setter protected boolean generateSortValidation = false;
+    @Setter protected boolean generatePageableConstraintValidation = false;
+
+    // Map from operationId to allowed sort values for @ValidSort annotation generation
+    private Map<String, List<String>> sortValidationEnums = new HashMap<>();
+    // Map from operationId to pageable defaults for @PageableDefault/@SortDefault annotation generation
+    private Map<String, SpringPageableScanUtils.PageableDefaultsData> pageableDefaultsRegistry = new HashMap<>();
+    // Map from operationId to pageable constraints for @ValidPageable annotation generation
+    private Map<String, SpringPageableScanUtils.PageableConstraintsData> pageableConstraintsRegistry = new HashMap<>();
 
     public SpringCodegen() {
         super();
@@ -338,6 +351,21 @@ 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=spring-boot.",
+                autoXSpringPaginated));
+        cliOptions.add(CliOption.newBoolean(GENERATE_SORT_VALIDATION,
+                "Generate a @ValidSort annotation and SortValidator class, and apply @ValidSort to paginated operations "
+                + "whose 'sort' parameter has enum values. Requires useBeanValidation=true and library=spring-boot.",
+                generateSortValidation));
+        cliOptions.add(CliOption.newBoolean(GENERATE_PAGEABLE_CONSTRAINT_VALIDATION,
+                "Generate a @ValidPageable annotation and PageableConstraintValidator class, and apply @ValidPageable to "
+                + "paginated operations whose 'page' or 'size' parameter has a maximum constraint. "
+                + "Requires useBeanValidation=true and library=spring-boot.",
+                generatePageableConstraintValidation));
 
     }
 
@@ -547,6 +575,12 @@ public void processOpts() {
 
         convertPropertyToBooleanAndWriteBack(ADDITIONAL_NOT_NULL_ANNOTATIONS, this::setAdditionalNotNullAnnotations);
 
+        if (SPRING_BOOT.equals(library)) {
+            convertPropertyToBooleanAndWriteBack(AUTO_X_SPRING_PAGINATED, this::setAutoXSpringPaginated);
+            convertPropertyToBooleanAndWriteBack(GENERATE_SORT_VALIDATION, this::setGenerateSortValidation);
+            convertPropertyToBooleanAndWriteBack(GENERATE_PAGEABLE_CONSTRAINT_VALIDATION, this::setGeneratePageableConstraintValidation);
+        }
+
         // override parent one
         importMapping.put("JsonDeserialize", (useJackson3 ? JACKSON3_PACKAGE : JACKSON2_PACKAGE) + ".databind.annotation.JsonDeserialize");
 
@@ -792,6 +826,33 @@ public void preprocessOpenAPI(OpenAPI openAPI) {
                     (sourceFolder + File.separator + configPackage).replace(".", java.io.File.separator), "EnumConverterConfiguration.java"));
         }
 
+        if (SPRING_BOOT.equals(library) && generateSortValidation && useBeanValidation) {
+            sortValidationEnums = SpringPageableScanUtils.scanSortValidationEnums(openAPI, autoXSpringPaginated);
+            if (!sortValidationEnums.isEmpty()) {
+                importMapping.putIfAbsent("ValidSort", configPackage + ".ValidSort");
+                supportingFiles.add(new SupportingFile("validSort.mustache",
+                        (sourceFolder + File.separator + configPackage).replace(".", java.io.File.separator), "ValidSort.java"));
+            }
+        }
+
+        if (SPRING_BOOT.equals(library)) {
+            pageableDefaultsRegistry = SpringPageableScanUtils.scanPageableDefaults(openAPI, autoXSpringPaginated);
+            if (!pageableDefaultsRegistry.isEmpty()) {
+                importMapping.putIfAbsent("PageableDefault", "org.springframework.data.web.PageableDefault");
+                importMapping.putIfAbsent("SortDefault", "org.springframework.data.web.SortDefault");
+                importMapping.putIfAbsent("Sort", "org.springframework.data.domain.Sort");
+            }
+        }
+
+        if (SPRING_BOOT.equals(library) && generatePageableConstraintValidation && useBeanValidation) {
+            pageableConstraintsRegistry = SpringPageableScanUtils.scanPageableConstraints(openAPI, autoXSpringPaginated);
+            if (!pageableConstraintsRegistry.isEmpty()) {
+                importMapping.putIfAbsent("ValidPageable", configPackage + ".ValidPageable");
+                supportingFiles.add(new SupportingFile("validPageable.mustache",
+                        (sourceFolder + File.separator + configPackage).replace(".", java.io.File.separator), "ValidPageable.java"));
+            }
+        }
+
         /*
          * TODO the following logic should not need anymore in OAS 3.0 if
          * ("/".equals(swagger.getBasePath())) { swagger.setBasePath(""); }
@@ -1114,6 +1175,24 @@ protected boolean isConstructorWithAllArgsAllowed(CodegenModel codegenModel) {
     @Override
     public CodegenOperation fromOperation(String path, String httpMethod, Operation operation, List<Server> servers) {
 
+        // Auto-detect pagination parameters and add x-spring-paginated if autoXSpringPaginated is enabled.
+        // Only for spring-boot; respect manual x-spring-paginated: false override.
+        if (SPRING_BOOT.equals(library) && autoXSpringPaginated) {
+            if (operation.getExtensions() == null || !Boolean.FALSE.equals(operation.getExtensions().get("x-spring-paginated"))) {
+                if (operation.getParameters() != null) {
+                    Set<String> paramNames = operation.getParameters().stream()
+                            .map(io.swagger.v3.oas.models.parameters.Parameter::getName)
+                            .collect(Collectors.toSet());
+                    if (paramNames.containsAll(Arrays.asList("page", "size", "sort"))) {
+                        if (operation.getExtensions() == null) {
+                            operation.setExtensions(new HashMap<>());
+                        }
+                        operation.getExtensions().put("x-spring-paginated", Boolean.TRUE);
+                    }
+                }
+            }
+        }
+
         // add Pageable import only if x-spring-paginated explicitly used
         // this allows to use a custom Pageable schema without importing Spring Pageable.
         if (Boolean.TRUE.equals(operation.getExtensions().get("x-spring-paginated"))) {
@@ -1142,6 +1221,56 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
             // #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));
+
+            // Build pageable parameter annotations (@ValidPageable, @ValidSort, @PageableDefault, @SortDefault.SortDefaults)
+            List<String> pageableAnnotations = new ArrayList<>();
+
+            if (generatePageableConstraintValidation && useBeanValidation && pageableConstraintsRegistry.containsKey(codegenOperation.operationId)) {
+                SpringPageableScanUtils.PageableConstraintsData constraints = pageableConstraintsRegistry.get(codegenOperation.operationId);
+                List<String> attrs = new ArrayList<>();
+                if (constraints.maxSize >= 0) attrs.add("maxSize = " + constraints.maxSize);
+                if (constraints.maxPage >= 0) attrs.add("maxPage = " + constraints.maxPage);
+                pageableAnnotations.add("@ValidPageable(" + String.join(", ", attrs) + ")");
+                codegenOperation.imports.add("ValidPageable");
+            }
+
+            if (generateSortValidation && useBeanValidation && sortValidationEnums.containsKey(codegenOperation.operationId)) {
+                List<String> allowedSortValues = sortValidationEnums.get(codegenOperation.operationId);
+                // Java annotation arrays use {} syntax
+                String allowedValuesStr = allowedSortValues.stream()
+                        .map(v -> "\"" + v.replace("\\", "\\\\").replace("\"", "\\\"") + "\"")
+                        .collect(Collectors.joining(", "));
+                pageableAnnotations.add("@ValidSort(allowedValues = {" + allowedValuesStr + "})");
+                codegenOperation.imports.add("ValidSort");
+            }
+
+            if (pageableDefaultsRegistry.containsKey(codegenOperation.operationId)) {
+                SpringPageableScanUtils.PageableDefaultsData defaults = pageableDefaultsRegistry.get(codegenOperation.operationId);
+                if (defaults.page != null || defaults.size != null) {
+                    List<String> attrs = new ArrayList<>();
+                    if (defaults.page != null) attrs.add("page = " + defaults.page);
+                    if (defaults.size != null) attrs.add("size = " + defaults.size);
+                    pageableAnnotations.add("@PageableDefault(" + String.join(", ", attrs) + ")");
+                    codegenOperation.imports.add("PageableDefault");
+                }
+                if (!defaults.sortDefaults.isEmpty()) {
+                    // Java annotation arrays use @SortDefault(...) with {} for the sort field array
+                    List<String> sortEntries = defaults.sortDefaults.stream()
+                            .map(sf -> "@SortDefault(sort = {\"" + sf.field + "\"}, direction = Sort.Direction." + sf.direction + ")")
+                            .collect(Collectors.toList());
+                    if (sortEntries.size() == 1) {
+                        pageableAnnotations.add("@SortDefault.SortDefaults(" + sortEntries.get(0) + ")");
+                    } else {
+                        pageableAnnotations.add("@SortDefault.SortDefaults({" + String.join(", ", sortEntries) + "})");
+                    }
+                    codegenOperation.imports.add("SortDefault");
+                    codegenOperation.imports.add("Sort");
+                }
+            }
+
+            if (!pageableAnnotations.isEmpty()) {
+                codegenOperation.vendorExtensions.put("x-pageable-extra-annotation", pageableAnnotations);
+            }
         }
         if (codegenOperation.vendorExtensions.containsKey("x-spring-provide-args") && !provideArgsClassSet.isEmpty()) {
             codegenOperation.imports.addAll(provideArgsClassSet);

modules/openapi-generator/src/main/resources/JavaSpring/api.mustache

@@ -279,7 +279,7 @@ public interface {{classname}} {
         {{#allParams}}{{>queryParams}}{{>pathParams}}{{>headerParams}}{{>bodyParams}}{{>formParams}}{{>cookieParams}}{{^-last}},
         {{/-last}}{{/allParams}}{{#includeHttpRequestContext}}{{#hasParams}},
         {{/hasParams}}{{#swagger2AnnotationLibrary}}@Parameter(hidden = true){{/swagger2AnnotationLibrary}} final {{#reactive}}ServerWebExchange exchange{{/reactive}}{{^reactive}}HttpServletRequest servletRequest{{/reactive}}{{/includeHttpRequestContext}}{{#vendorExtensions.x-spring-paginated}}{{#hasParams}},
-        {{/hasParams}}{{^hasParams}}{{#includeHttpRequestContext}},{{/includeHttpRequestContext}}{{/hasParams}}{{#springDocDocumentationProvider}}@ParameterObject{{/springDocDocumentationProvider}} final Pageable pageable{{/vendorExtensions.x-spring-paginated}}{{#vendorExtensions.x-spring-provide-args}}{{#hasParams}},
+        {{/hasParams}}{{^hasParams}}{{#includeHttpRequestContext}},{{/includeHttpRequestContext}}{{/hasParams}}{{#vendorExtensions.x-pageable-extra-annotation}}{{{.}}} {{/vendorExtensions.x-pageable-extra-annotation}}{{#springDocDocumentationProvider}}@ParameterObject{{/springDocDocumentationProvider}} final Pageable pageable{{/vendorExtensions.x-spring-paginated}}{{#vendorExtensions.x-spring-provide-args}}{{#hasParams}},
         {{/hasParams}}{{^hasParams}}{{#includeHttpRequestContext}},{{/includeHttpRequestContext}}{{/hasParams}}{{#swagger2AnnotationLibrary}}@Parameter(hidden = true){{/swagger2AnnotationLibrary}} {{{.}}}{{^hasParams}}{{^-last}}{{^reactive}},{{/reactive}}
         {{/-last}}{{/hasParams}}{{/vendorExtensions.x-spring-provide-args}}
     ){{#unhandledException}} throws Exception{{/unhandledException}}{{^jdk8-default-interface}};{{/jdk8-default-interface}}{{#jdk8-default-interface}} {

modules/openapi-generator/src/main/resources/JavaSpring/validPageable.mustache

@@ -0,0 +1,95 @@
+package {{configPackage}};
+
+import {{javaxPackage}}.validation.Constraint;
+import {{javaxPackage}}.validation.ConstraintValidator;
+import {{javaxPackage}}.validation.ConstraintValidatorContext;
+import {{javaxPackage}}.validation.Payload;
+import org.springframework.data.domain.Pageable;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Validates that the page number and page size in the annotated {@link Pageable} parameter do not
+ * exceed their configured maximums.
+ *
+ * <p>Apply directly on a {@code Pageable} parameter. Each attribute is independently optional:
+ * <ul>
+ *   <li>{@link #maxSize()} — when set (&gt;= 0), validates {@code pageable.getPageSize() <= maxSize}
+ *   <li>{@link #maxPage()} — when set (&gt;= 0), validates {@code pageable.getPageNumber() <= maxPage}
+ * </ul>
+ *
+ * <p>Use {@link #NO_LIMIT} (= {@code -1}, the default) to leave an attribute unconstrained.
+ *
+ * <p>Constraining {@link #maxPage()} is useful to prevent deep-pagination attacks, where a large
+ * page offset (e.g. {@code ?page=100000&size=20}) causes an expensive {@code OFFSET} query on the
+ * database.
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Constraint(validatedBy = {ValidPageable.PageableConstraintValidator.class})
+@Target({ElementType.PARAMETER})
+public @interface ValidPageable {
+
+    /** Sentinel value meaning no limit is applied. */
+    int NO_LIMIT = -1;
+
+    /** Maximum allowed page size, or {@link #NO_LIMIT} if unconstrained. */
+    int maxSize() default NO_LIMIT;
+
+    /** Maximum allowed page number (0-based), or {@link #NO_LIMIT} if unconstrained. */
+    int maxPage() default NO_LIMIT;
+
+    Class<?>[] groups() default {};
+
+    Class<? extends Payload>[] payload() default {};
+
+    String message() default "Invalid page request";
+
+    class PageableConstraintValidator implements ConstraintValidator<ValidPageable, Pageable> {
+
+        private int maxSize = NO_LIMIT;
+        private int maxPage = NO_LIMIT;
+
+        @Override
+        public void initialize(ValidPageable constraintAnnotation) {
+            maxSize = constraintAnnotation.maxSize();
+            maxPage = constraintAnnotation.maxPage();
+        }
+
+        @Override
+        public boolean isValid(Pageable pageable, ConstraintValidatorContext context) {
+            if (pageable == null) {
+                return true;
+            }
+
+            boolean valid = true;
+            context.disableDefaultConstraintViolation();
+
+            if (maxSize >= 0 && pageable.getPageSize() > maxSize) {
+                context.buildConstraintViolationWithTemplate(
+                                context.getDefaultConstraintMessageTemplate()
+                                        + ": page size " + pageable.getPageSize()
+                                        + " exceeds maximum " + maxSize)
+                        .addPropertyNode("size")
+                        .addConstraintViolation();
+                valid = false;
+            }
+
+            if (maxPage >= 0 && pageable.getPageNumber() > maxPage) {
+                context.buildConstraintViolationWithTemplate(
+                                context.getDefaultConstraintMessageTemplate()
+                                        + ": page number " + pageable.getPageNumber()
+                                        + " exceeds maximum " + maxPage)
+                        .addPropertyNode("page")
+                        .addConstraintViolation();
+                valid = false;
+            }
+
+            return valid;
+        }
+    }
+}