Package org.openapitools.codegen.languages

Class SpringPageableScanUtils

  • public class SpringPageableScanUtils
extends Object
    Utility class for scanning OpenAPI specs for Spring Pageable-related features: sort enum validation, pageable defaults, and pageable constraints (max page/size).

    Can be used as a static utility or instantiated to hold the scan results (sortValidationEnums, pageableDefaultsRegistry, pageableConstraintsRegistry) so that callers do not need to maintain those maps themselves. Call scanAll(OpenAPI, boolean) once in preprocessOpenAPI to populate them, then access the fields directly.

    Used by both kotlin KotlinSpringServerCodegen and java SpringCodegen to share scan and annotation-building logic. Only the mustache templates and their registration remain language-specific.

    • Constructor Detail

      • SpringPageableScanUtils

        public SpringPageableScanUtils()

    • Method Detail

      • scanAll

        public void scanAll​(io.swagger.v3.oas.models.OpenAPI openAPI,
                    boolean autoXSpringPaginated)
        Populates sortValidationEnums, pageableDefaultsRegistry, and pageableConstraintsRegistry by scanning the given OpenAPI document.

        Call this once from preprocessOpenAPI (guarded by your library check), then read the public map fields in fromOperation.

        Parameters:
        openAPI - the OpenAPI document to scan
        autoXSpringPaginated - whether auto-detection of pageable operations is enabled

      • willBePageable

        public static boolean willBePageable​(io.swagger.v3.oas.models.Operation operation,
                                     boolean autoXSpringPaginated)
        Returns true if the given operation will have a Pageable parameter injected — either because it has x-spring-paginated: true explicitly, or because autoXSpringPaginated is enabled and the operation has all three default pagination query parameters (page, size, sort).

      • getXSpringPaginated

        public static Boolean getXSpringPaginated​(io.swagger.v3.oas.models.Operation operation)
        Returns the resolved `x-spring-paginated` flag.
        Returns:
        `Boolean.TRUE`/`Boolean.FALSE` when explicitly set, otherwise `null`

      • applyAutoXSpringPaginatedIfNeeded

        public static boolean applyAutoXSpringPaginatedIfNeeded​(io.swagger.v3.oas.models.Operation operation,
                                                        boolean autoXSpringPaginated)
        Auto-detects Pageable pagination query parameters and, when detected, mutates the operation by setting x-spring-paginated: true on its vendor extensions.

        Detection is delegated to willBePageable(Operation, boolean). If the operation is already explicitly flagged (x-spring-paginated: true/false) this method is a read-only pass-through — it returns the explicit value without mutating extensions. Only auto-detected operations (those whose flag was null) have the extension written.

        This method centralises the "detect + mutate" logic shared by both SpringCodegen and KotlinSpringServerCodegen inside their fromOperation overrides. It must be called before super.fromOperation() so that the base codegen can pick up the extension when populating CodegenOperation.vendorExtensions.

        Parameters:
        operation - the raw OpenAPI Operation to inspect (and possibly mutate)
        autoXSpringPaginated - whether auto-detection is enabled for this generator
        Returns:
        true if the operation is (or was just marked as) paginated

      • removePageableQueryParams

        public static void removePageableQueryParams​(CodegenOperation codegenOperation)
        Removes the three Spring Data Web default pagination query parameters (page, size, sort) from the given codegen operation's parameter lists.

        When an operation is marked with x-spring-paginated, Spring injects a single org.springframework.data.domain.Pageable parameter that internally handles page, size, and sort. The individual query parameters must therefore be removed from the generated method signature.

        Callers are responsible for ensuring this is only invoked for server-side library configurations (spring-boot) where Pageable injection actually takes place.

        Parameters:
        codegenOperation - the operation whose parameter lists should be pruned

      • applyPageableAnnotations

        public static void applyPageableAnnotations​(CodegenOperation codegenOperation,
                                            boolean generatePageableConstraintValidation,
                                            boolean useBeanValidation,
                                            Map<String,​SpringPageableScanUtils.PageableConstraintsData> pageableConstraintsRegistry,
                                            boolean generateSortValidation,
                                            Map<String,​List<String>> sortValidationEnums,
                                            Map<String,​SpringPageableScanUtils.PageableDefaultsData> pageableDefaultsRegistry,
                                            SpringPageableScanUtils.AnnotationSyntax syntax)
        Builds and attaches the pageable-parameter annotations (@ValidPageable, @ValidSort, @PageableDefault, @SortDefault.SortDefaults) to the given codegen operation.

        The annotations and their imports are only added when the relevant feature flags (generatePageableConstraintValidation, generateSortValidation) are enabled and a matching entry exists in the corresponding registry for this operation. The result is stored under the x-pageable-extra-annotation vendor extension.

        Language-specific differences in annotation array syntax (Java {...} vs Kotlin [...]) are handled by the syntax parameter. SpringDoc-specific import additions remain in each calling codegen class since they differ between Java (ParameterObject) and Kotlin (PageableAsQueryParam + x-operation-extra-annotation mutation).

        Parameters:
        codegenOperation - the operation to annotate
        generatePageableConstraintValidation - whether to emit @ValidPageable
        useBeanValidation - whether bean validation is active
        pageableConstraintsRegistry - per-operationId constraint data
        generateSortValidation - whether to emit @ValidSort
        sortValidationEnums - per-operationId allowed sort values
        pageableDefaultsRegistry - per-operationId default page/size/sort data
        syntax - target language annotation syntax

      • applySpringDocPageableAnnotation

        public static void applySpringDocPageableAnnotation​(CodegenOperation codegenOperation,
                                                    SpringPageableScanUtils.AnnotationSyntax syntax,
                                                    boolean isSpringDoc)
        Applies SpringDoc-specific annotation handling for a pageable operation.

        When isSpringDoc is true:

        • Java: adds the ParameterObject import, which instructs SpringDoc to expose the individual pageable query parameters in the OpenAPI UI.
        • Kotlin: adds the PageableAsQueryParam import and prepends @PageableAsQueryParam to the operation's x-operation-extra-annotation vendor extension so the Mustache template renders it on the generated controller method.

        When isSpringDoc is false this method is a no-op.

        Parameters:
        codegenOperation - the operation to annotate
        syntax - target language annotation syntax
        isSpringDoc - whether the active documentation provider is SpringDoc

      • scanSortValidationEnums

        public static Map<String,​List<String>> scanSortValidationEnums​(io.swagger.v3.oas.models.OpenAPI openAPI,
                                                                     boolean autoXSpringPaginated)
        Scans all pageable operations for a sort parameter with enum values.
        Returns:
        map from operationId to list of allowed sort strings (e.g. ["id,asc", "id,desc"])

      • scanPageableConstraints

        public static Map<String,​SpringPageableScanUtils.PageableConstraintsData> scanPageableConstraints​(io.swagger.v3.oas.models.OpenAPI openAPI,
                                                                                                        boolean autoXSpringPaginated)
        Scans all pageable operations for maximum: and minimum: constraints on page and size parameters. Values are resolved through allOf and $ref schemas so that constraints defined on shared component schemas are honoured.
        Returns:
        map from operationId to SpringPageableScanUtils.PageableConstraintsData (only operations with at least one constraint are included)