feat: enhance pageable validation with sort enum support

Author: Picazsoo

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

@@ -1059,27 +1059,21 @@ 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
-                // Before removal, capture sort enum values for @ValidSort if generateSortValidation is enabled
+                // Build pageable parameter annotations (@ValidSort, @PageableDefault, @SortDefault.SortDefaults)
+                List<String> pageableAnnotations = new ArrayList<>();
+
                 if (generateSortValidation && useBeanValidation && sortValidationEnums.containsKey(codegenOperation.operationId)) {
                     List<String> allowedSortValues = sortValidationEnums.get(codegenOperation.operationId);
                     String allowedValuesStr = allowedSortValues.stream()
                             .map(v -> "\"" + v.replace("\\", "\\\\").replace("\"", "\\\"") + "\"")
                             .collect(Collectors.joining(", "));
-                    String validSortAnnotation = "@ValidSort(allowedValues = [" + allowedValuesStr + "])";
-
-                    Object existingAnnotation = codegenOperation.vendorExtensions.get("x-operation-extra-annotation");
-                    List<String> existingAnnotations = DefaultCodegen.getObjectAsStringList(existingAnnotation);
-                    List<String> updatedAnnotations = new ArrayList<>(existingAnnotations);
-                    updatedAnnotations.add(validSortAnnotation);
-                    codegenOperation.vendorExtensions.put("x-operation-extra-annotation", updatedAnnotations);
-
+                    pageableAnnotations.add("@ValidSort(allowedValues = [" + allowedValuesStr + "])");
                     codegenOperation.imports.add("ValidSort");
                 }
 
                 // Generate @PageableDefault / @SortDefault.SortDefaults annotations if defaults are present
                 if (pageableDefaultsRegistry.containsKey(codegenOperation.operationId)) {
                     PageableDefaultsData defaults = pageableDefaultsRegistry.get(codegenOperation.operationId);
-                    List<String> pageableAnnotations = new ArrayList<>();
 
                     if (defaults.page != null || defaults.size != null) {
                         List<String> attrs = new ArrayList<>();
@@ -1097,10 +1091,10 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
                         codegenOperation.imports.add("SortDefault");
                         codegenOperation.imports.add("Sort");
                     }
+                }
 
-                    if (!pageableAnnotations.isEmpty()) {
-                        codegenOperation.vendorExtensions.put("x-pageable-extra-annotation", pageableAnnotations);
-                    }
+                if (!pageableAnnotations.isEmpty()) {
+                    codegenOperation.vendorExtensions.put("x-pageable-extra-annotation", pageableAnnotations);
                 }
                 codegenOperation.queryParams.removeIf(param -> defaultPageableQueryParams.contains(param.baseName));
                 codegenOperation.allParams.removeIf(param -> param.isQueryParam && defaultPageableQueryParams.contains(param.baseName));

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

@@ -4,18 +4,25 @@ import {{javaxPackage}}.validation.Constraint
 import {{javaxPackage}}.validation.ConstraintValidator
 import {{javaxPackage}}.validation.ConstraintValidatorContext
 import {{javaxPackage}}.validation.Payload
-import {{javaxPackage}}.validation.constraintvalidation.SupportedValidationTarget
-import {{javaxPackage}}.validation.constraintvalidation.ValidationTarget
 import org.springframework.data.domain.Pageable
 
 /**
- * Validates that sort properties in a [Pageable] parameter match the allowed values.
+ * Validates that sort properties in the annotated [Pageable] parameter match the allowed values.
  *
- * This annotation can only be applied to methods that have a [Pageable] parameter.
- * The validator checks that each sort property and direction combination in the [Pageable]
- * matches one of the strings specified in [allowedValues].
+ * Apply directly on a `pageable: Pageable` parameter. The validator checks that each sort
+ * property and direction combination in the [Pageable] matches one of the strings specified
+ * in [allowedValues].
  *
- * Expected value format: `"property,direction"` (e.g. `"id,asc"`, `"name,desc"`).
+ * Two formats are accepted in [allowedValues]:
+ * - `"property,direction"` — permits only the specific direction (e.g. `"id,asc"`, `"name,desc"`).
+ *   Direction matching is case-insensitive: `"id,ASC"` and `"id,asc"` are treated identically.
+ * - `"property"` — permits any direction for that property (e.g. `"id"` matches `sort=id,asc`
+ *   and `sort=id,desc`). Note: because Spring always normalises a bare `sort=id` to ascending
+ *   before the validator runs, bare property names in [allowedValues] effectively allow all
+ *   directions — the original omission of a direction cannot be detected.
+ *
+ * Both formats may be mixed freely. For example `["id", "name,desc"]` allows `id` in any
+ * direction but restricts `name` to descending only.
  *
  * @property allowedValues The allowed sort strings (e.g. `["id,asc", "id,desc"]`)
  * @property groups Validation groups (optional)
@@ -25,34 +32,38 @@ import org.springframework.data.domain.Pageable
 @MustBeDocumented
 @Retention(AnnotationRetention.RUNTIME)
 @Constraint(validatedBy = [SortValidator::class])
-@Target(AnnotationTarget.FUNCTION)
+@Target(AnnotationTarget.VALUE_PARAMETER)
 annotation class ValidSort(
     val allowedValues: Array<String>,
     val groups: Array<kotlin.reflect.KClass<*>> = [],
     val payload: Array<kotlin.reflect.KClass<out Payload>> = [],
     val message: String = "Invalid sort column"
 )
 
-@SupportedValidationTarget(ValidationTarget.PARAMETERS)
-class SortValidator : ConstraintValidator<ValidSort, Array<Any?>> {
+class SortValidator : ConstraintValidator<ValidSort, Pageable> {
 
     private lateinit var allowedValues: Set<String>
 
     override fun initialize(constraintAnnotation: ValidSort) {
-        allowedValues = constraintAnnotation.allowedValues.toSet()
+        allowedValues = constraintAnnotation.allowedValues.map { entry ->
+            DIRECTION_ASC_SUFFIX.replace(entry, ",asc")
+                .let { DIRECTION_DESC_SUFFIX.replace(it, ",desc") }
+        }.toSet()
+    }
+
+    private companion object {
+        val DIRECTION_ASC_SUFFIX = Regex(",ASC$", RegexOption.IGNORE_CASE)
+        val DIRECTION_DESC_SUFFIX = Regex(",DESC$", RegexOption.IGNORE_CASE)
     }
 
-    override fun isValid(parameters: Array<Any?>?, context: ConstraintValidatorContext): Boolean {
-        val pageable = parameters?.filterIsInstance<Pageable>()?.firstOrNull()
-            ?: throw IllegalStateException(
-                "@ValidSort can only be used on methods with a Pageable parameter. " +
-                    "Ensure the annotated method has a parameter of type org.springframework.data.domain.Pageable."
-            )
+    override fun isValid(pageable: Pageable?, context: ConstraintValidatorContext): Boolean {
+        if (pageable == null || pageable.sort.isUnsorted) return true
 
         val invalid = pageable.sort
             .foldIndexed(emptyMap<Int, String>()) { index, acc, order ->
                 val sortValue = "${order.property},${order.direction.name.lowercase()}"
-                if (sortValue !in allowedValues) acc + (index to order.property)
+                // Accept "property,direction" (exact match) OR "property" alone (any direction allowed)
+                if (sortValue !in allowedValues && order.property !in allowedValues) acc + (index to order.property)
                 else acc
             }
             .toSortedMap()

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

@@ -4177,6 +4177,21 @@ public void generateSortValidationAddsAnnotationForExplicitPaginated() throws Ex
         File petApi = files.get("PetApi.kt");
         assertFileContains(petApi.toPath(), "@ValidSort(allowedValues = [\"id,asc\", \"id,desc\", \"name,asc\", \"name,desc\"])");
         assertFileContains(petApi.toPath(), "import org.openapitools.configuration.ValidSort");
+
+        // @ValidSort must be a parameter annotation — appears in the 500-char window AFTER `fun findPetsWithSortEnum(`
+        String content = Files.readString(petApi.toPath());
+        int methodStart = content.indexOf("fun findPetsWithSortEnum(");
+        Assert.assertTrue(methodStart >= 0, "findPetsWithSortEnum method should exist");
+        String paramBlock = content.substring(methodStart, Math.min(content.length(), methodStart + 500));
+        Assert.assertTrue(paramBlock.contains("@ValidSort(allowedValues = [\"id,asc\", \"id,desc\", \"name,asc\", \"name,desc\"])"),
+                "@ValidSort should appear as a parameter annotation (inside the method signature, after `fun`)");
+        Assert.assertTrue(paramBlock.contains("pageable: Pageable"),
+                "findPetsWithSortEnum should have a pageable: Pageable parameter");
+
+        // @ValidSort must NOT be a method-level annotation (not in the 500-char prefix before `fun`)
+        String prefixBlock = content.substring(Math.max(0, methodStart - 500), methodStart);
+        Assert.assertFalse(prefixBlock.contains("@ValidSort"),
+                "@ValidSort should be a parameter annotation, not a method-level annotation");
     }
 
     @Test
@@ -4265,7 +4280,8 @@ public void generateSortValidationGeneratesValidSortFile() throws Exception {
         assertFileContains(validSortFile.toPath(), "annotation class ValidSort");
         assertFileContains(validSortFile.toPath(), "class SortValidator");
         assertFileContains(validSortFile.toPath(), "val allowedValues: Array<String>");
-        assertFileContains(validSortFile.toPath(), "allowedValues.toSet()");
+        assertFileContains(validSortFile.toPath(), "DIRECTION_ASC_SUFFIX");
+        assertFileContains(validSortFile.toPath(), "DIRECTION_DESC_SUFFIX");
     }
 
     @Test