OpenAPITools / OpenAPITools/openapi-generator

[BUG][Spring] @ValidPageable / @PageableDefault / @SortDefault are never applied when the operationId needs sanitizing

Open
#24,721 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

The pageable scan registries of SpringPageableScanUtils (pageableConstraintsRegistry,
pageableDefaultsRegistry, sortValidationEnums) are keyed by the raw operationId read from the
document:

registry.put(operation.getOperationId(), ...);

but applyPageableAnnotations looks them up by CodegenOperation.operationId, which is the sanitized
one. Whenever the document uses an operationId that codegen rewrites (anything not already
lowerCamelCase, e.g. list-items -> listItems), the lookup misses and none of @ValidPageable,
@PageableDefault or @SortDefault is ever emitted. The Pageable parameter itself is generated
correctly, so the failure is silent: the constraints declared in the spec (maximum, minimum, default,
enum) are simply not enforced.

This also makes the generated output inconsistent: SpringCodegen#preprocessOpenAPI registers the
ValidPageable.java supporting file based only on the registry being non-empty, so the annotation class is
generated but never used.

openapi-generator version

7.24.0 (the affected options were introduced in this version).

OpenAPI declaration file

The two documents below are identical except for the operationId.

Fails — operationId: list-items:

openapi: 3.0.3
info:
  title: Inline params API
  version: "1.0"
paths:
  /items:
    get:
      operationId: list-items
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
        - name: size
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
        - name: sort
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

Works — the same file with operationId: listItems.

Generation details

<generatorName>spring</generatorName>
<library>spring-boot</library>
<configOptions>
  <useSpringBoot3>true</useSpringBoot3>
  <useBeanValidation>true</useBeanValidation>
  <autoXSpringPaginated>true</autoXSpringPaginated>
  <generatePageableConstraintValidation>true</generatePageableConstraintValidation>
</configOptions>

Steps to reproduce

  1. Generate both documents with the configuration above.
  2. Compare the generated ItemsApi.java.

With operationId: listItems:

@ValidPageable(maxSize = 100, minSize = 1, minPage = 0) @PageableDefault(page = 0, size = 20) @ParameterObject final Pageable pageable

With operationId: list-items:

@ParameterObject final Pageable pageable

Suggest a fix

Make both sides use the same key. Either key the registries by the sanitized id when scanning
(toOperationId(operation.getOperationId())), or pass the raw operationId down to
applyPageableAnnotations and look up with it. The second option is probably safer, since the sanitized id
is only known once CodegenOperation has been built.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading SpringPageableScanUtils, especially the pageable registries and applyPageableAnnotations, then inspect SpringCodegen#preprocessOpenAPI. Reproduce generation with the supplied list-items and listItems specifications and configuration. Done means sanitized operation IDs still produce @ValidPageable, @PageableDefault, and @SortDefault when the corresponding constraints or defaults are present.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi, spring
Domain
api, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
75/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.