You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 979c44b
Browse filesBrowse the repository at this point in the historyBrowse files
[JAVA-SPRING;KOTLIN-SPRING] improvement: Allow autoXSpringPaginated for endpoints without sort (#24863)
* Allow autoXSpringPaginated for endpoints without sort
Change autoXSpringPaginated from a boolean switch into a string-enum option
with three canonical values:
- none: disable auto-detection (default)
- page-size-sort: require page, size, and sort query parameters (identical
to the previous true behavior)
- page-size: require only page and size; sort may be absent (new)
The legacy true/false values are still accepted as deprecated aliases for
page-size-sort/none respectively. A deprecation warning is logged once via
the generator logger only when the option is explicitly set to true/false;
leaving the option unset keeps the silent none default with no warning.
- Add SpringPageableScanUtils.AutoPaginationMode enum and
resolveAutoPaginationMode() to centralize parsing/validation/deprecation
warnings shared by SpringCodegen and KotlinSpringServerCodegen.
- Update willBePageable, applyAutoXSpringPaginatedIfNeeded, and the
scanSortValidationEnums/scanPageableDefaults/scanPageableConstraints/
scanAll methods to take AutoPaginationMode instead of boolean.
- Replace the boolean CLI switch with a documented string-enum CLI option
in SpringCodegen and KotlinSpringServerCodegen (JavaCamelServerCodegen
inherits the behavior since it extends SpringCodegen).
- Update existing tests to use the new enum where internal signatures
changed; add new tests for page-size mode detection, deprecation
warnings (once when explicit, never when unset), and invalid values.
- Regenerate docs/generators/{spring,kotlin-spring,java-camel}.md.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Restore autoXSpringPaginated setter compatibility
Preserve public string and deprecated boolean setter APIs for Spring and Kotlin Spring generators. Keep Kotlin autoXSpringPaginated absent from additionalProperties when it is unset, matching Spring behavior. Replace binding-dependent logback test capture with direct setter and option-state assertions.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Centralize autoXSpringPaginated option values
Share the immutable auto-pagination CLI enum map from SpringPageableScanUtils so Spring and Kotlin Spring generators cannot diverge.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix pageable scanAll Javadoc reference
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* remove sample file
* Revert "remove sample file"
This reverts commit c6bcdb2.
* Fix PR review findings in SpringPageableScanUtils
- Filter resolved parameters to in:query before checking required
names in willBePageable(), so non-query parameters named 'page'/
'size' no longer cause PAGE_SIZE auto-detection false positives.
- Guard the legacy true/false deprecation warning in
SpringCodegen/KotlinSpringServerCodegen's setAutoXSpringPaginated
setters with a per-instance flag, so repeated setter/option-
processing calls only log the warning once.
- Add regression test for path/header parameters named page/size
not triggering PAGE_SIZE auto-detection.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Restore deprecation-warning tests and add missing regression coverage
- Restore logback ListAppender tests in SpringCodegenTest and
KotlinSpringServerCodegenTest asserting the legacy true/false
deprecation warning is logged exactly once when explicitly set and
not at all when unset, plus a new test proving the setter's
once-only guard suppresses a second warning when invoked twice with
the same legacy value.
- Add willBePageable_pageSizeSortMode_doesNotDetectPathParamNamedSort
to lock in the query-location filter for PAGE_SIZE_SORT (previously
only regression-tested for PAGE_SIZE).
- Add .in("query") to the page/size params in
applyAutoXSpringPaginatedIfNeeded_autoDisabled_doesNotSetExtension
and applyAutoXSpringPaginatedIfNeeded_explicitlyFalse_returnsFalseAndIsNotOverridden
so they exercise real auto-detection instead of passing trivially.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Filter ListAppender events by thread in deprecation-warning tests
Surefire runs test classes in parallel (parallel=classes,
threadCountClasses=3), and SpringCodegen/KotlinSpringServerCodegen log
through a shared per-class-name logback Logger inherited by all
subclasses. A ListAppender attached to that logger during these tests
could capture log events emitted by concurrently-running test classes
on other threads, causing flaky/incorrect exactly-once and no-warning
assertions. Filter captured events to the current test thread before
asserting.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Snapshot ListAppender events under the appender lock in deprecation-warning tests
ListAppender.list is a plain ArrayList that concurrently-running test
classes may still append to. Copy it while holding the appender monitor
(the same lock AppenderBase.doAppend uses) before filtering by thread.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* update samples
* Validate autoXSpringPaginated for all libraries and dedupe warn-once logic
- Resolve and validate an explicitly supplied autoXSpringPaginated value
in SpringCodegen and KotlinSpringServerCodegen regardless of library,
so invalid values are no longer silently ignored for
spring-http-interface / spring-declarative-http-interface. Write-back
and usage remain gated by isPageableSupported().
- Move the once-only deprecation-warning guard into
SpringPageableScanUtils.warnOnce(Consumer) shared by both generators.
- Extract a countDeprecationWarnings(Runnable) helper in the Spring and
Kotlin Spring codegen tests, and add regression tests for validation
on unsupported libraries and for warnOnce.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Extract shared log-capture helper into TestUtils
Move the ListAppender attach/detach, monitor-guarded snapshot and
current-thread filtering duplicated in SpringCodegenTest and
KotlinSpringServerCodegenTest into TestUtils.captureLogMessages, leaving
a thin per-class countDeprecationWarnings wrapper.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Simplify autoXSpringPaginated deprecation warning
The setter is only called once per generation (from processOpts), so the
warn-once machinery guarded a case that never occurs in practice.
- Make SpringPageableScanUtils.resolveAutoPaginationMode(String) pure.
- Add package-private warnIfDeprecatedAutoPaginationValue, called once
from processOpts in SpringCodegen and KotlinSpringServerCodegen; it
shares value normalization with resolve.
- Remove warnOnce and the per-generator guard fields.
- Adapt tests and drop the ones made redundant by the
processOpts-logs-exactly-once tests.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix archunit violation
* Fix static-context compile error by making warnIfDeprecatedAutoPaginationValue instance method
LOGGER in SpringPageableScanUtils is intentionally a non-static instance
field (enforced by ArchUnitRulesTest to limit memory use across
generator instances), so it cannot be referenced from a static method.
Change warnIfDeprecatedAutoPaginationValue from static to instance
scope and call it via the existing pageableUtils instance in
SpringCodegen and KotlinSpringServerCodegen. Update the corresponding
unit tests to invoke it on a SpringPageableScanUtils instance.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copy file name to clipboardExpand all lines: docs/generators/java-camel.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
31
31
|artifactUrl|artifact URL in generated pom.xml||https://github.com/openapitools/openapi-generator|
32
32
|artifactVersion|artifact version in generated pom.xml. This also becomes part of the generated library's filename. If not provided, uses the version from the OpenAPI specification file. If that's also not present, uses the default value of the artifactVersion option.||1.0.0|
33
33
|async|use async Callable controllers||false|
34
-
|autoXSpringPaginated|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 is spring-boot or spring-cloud.||false|
34
+
|autoXSpringPaginated|Automatically add x-spring-paginated to operations that have the given set of pagination query parameters. 'page-size-sort' requires 'page', 'size', and 'sort'; 'page-size' requires only 'page' and 'size' (sort may be absent). Operations with x-spring-paginated explicitly set to false will not be auto-detected. Only applies when library is spring-boot or spring-cloud. The legacy values 'true' (alias for 'page-size-sort') and 'false' (alias for 'none') are deprecated and will be removed in a future release.|<dl><dt>**none**</dt><dd>Disable auto-detection.</dd><dt>**page-size-sort**</dt><dd>Require 'page', 'size', and 'sort' query parameters.</dd><dt>**page-size**</dt><dd>Require only 'page' and 'size' query parameters.</dd><dt>**true**</dt><dd>(deprecated) alias for 'page-size-sort'.</dd><dt>**false**</dt><dd>(deprecated) alias for 'none'.</dd></dl>|none|
35
35
|basePackage|base package (invokerPackage) for generated code||org.openapitools|
36
36
|bigDecimalAsString|Treat BigDecimal values as Strings to avoid precision loss.||false|
|autoXSpringPaginated|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.||false|
27
+
|autoXSpringPaginated|Automatically add x-spring-paginated to operations that have the given set of pagination query parameters. 'page-size-sort' requires 'page', 'size', and 'sort'; 'page-size' requires only 'page' and 'size' (sort may be absent). Operations with x-spring-paginated explicitly set to false will not be auto-detected. The legacy values 'true' (alias for 'page-size-sort') and 'false' (alias for 'none') are deprecated and will be removed in a future release.|<dl><dt>**none**</dt><dd>Disable auto-detection.</dd><dt>**page-size-sort**</dt><dd>Require 'page', 'size', and 'sort' query parameters.</dd><dt>**page-size**</dt><dd>Require only 'page' and 'size' query parameters.</dd><dt>**true**</dt><dd>(deprecated) alias for 'page-size-sort'.</dd><dt>**false**</dt><dd>(deprecated) alias for 'none'.</dd></dl>|none|
28
28
|basePackage|base package (invokerPackage) for generated code||org.openapitools|
29
29
|beanQualifiers|Whether to add fully-qualifier class names as bean qualifiers in @Component and @RestController annotations. May be used to prevent bean names clash if multiple generated libraries (contexts) added to single project.||false|
30
30
|companionObject|Whether to generate companion objects in data classes, enabling companion extensions.||false|
Copy file name to clipboardExpand all lines: docs/generators/spring.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
31
31
|artifactUrl|artifact URL in generated pom.xml||https://github.com/openapitools/openapi-generator|
32
32
|artifactVersion|artifact version in generated pom.xml. This also becomes part of the generated library's filename. If not provided, uses the version from the OpenAPI specification file. If that's also not present, uses the default value of the artifactVersion option.||1.0.0|
33
33
|async|use async Callable controllers||false|
34
-
|autoXSpringPaginated|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 is spring-boot or spring-cloud.||false|
34
+
|autoXSpringPaginated|Automatically add x-spring-paginated to operations that have the given set of pagination query parameters. 'page-size-sort' requires 'page', 'size', and 'sort'; 'page-size' requires only 'page' and 'size' (sort may be absent). Operations with x-spring-paginated explicitly set to false will not be auto-detected. Only applies when library is spring-boot or spring-cloud. The legacy values 'true' (alias for 'page-size-sort') and 'false' (alias for 'none') are deprecated and will be removed in a future release.|<dl><dt>**none**</dt><dd>Disable auto-detection.</dd><dt>**page-size-sort**</dt><dd>Require 'page', 'size', and 'sort' query parameters.</dd><dt>**page-size**</dt><dd>Require only 'page' and 'size' query parameters.</dd><dt>**true**</dt><dd>(deprecated) alias for 'page-size-sort'.</dd><dt>**false**</dt><dd>(deprecated) alias for 'none'.</dd></dl>|none|
35
35
|basePackage|base package (invokerPackage) for generated code||org.openapitools|
36
36
|bigDecimalAsString|Treat BigDecimal values as Strings to avoid precision loss.||false|
@@ -313,7 +333,13 @@ public KotlinSpringServerCodegen() {
313
333
addOption(X_KOTLIN_IMPLEMENTS_FIELDS_SKIP, "A list of fields per schema name that should NOT be created with `override` keyword despite their presence in vendor extension `x-kotlin-implements-fields` for the schema. Example: yaml `xKotlinImplementsFieldsSkip: Pet: [photoUrls]` skips `override` for `photoUrls` in schema `Pet`", "empty map");
314
334
addOption(SCHEMA_IMPLEMENTS, "A map of single interface or a list of interfaces per schema name that should be implemented (serves similar purpose as `x-kotlin-implements`, but is fully decoupled from the api spec). Example: yaml `schemaImplements: {Pet: com.some.pack.WithId, Category: [com.some.pack.CategoryInterface], Dog: [com.some.pack.Canine, com.some.pack.OtherInterface]}` implements interfaces in schemas `Pet` (interface `com.some.pack.WithId`), `Category` (interface `com.some.pack.CategoryInterface`), `Dog`(interfaces `com.some.pack.Canine`, `com.some.pack.OtherInterface`)", "empty map");
315
335
addOption(SCHEMA_IMPLEMENTS_FIELDS, "A map of single field or a list of fields per schema name that should be prepended with `override` (serves similar purpose as `x-kotlin-implements-fields`, but is fully decoupled from the api spec). Example: yaml `schemaImplementsFields: {Pet: id, Category: [name, id], Dog: [bark, breed]}` marks fields to be prepended with `override` in schemas `Pet` (field `id`), `Category` (fields `name`, `id`) and `Dog` (fields `bark`, `breed`)", "empty map");
316
-
addSwitch(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.", autoXSpringPaginated);
336
+
addOption(AUTO_X_SPRING_PAGINATED,
337
+
"Automatically add x-spring-paginated to operations that have the given set of pagination query "
338
+
+ "parameters. 'page-size-sort' requires 'page', 'size', and 'sort'; 'page-size' requires only "
339
+
+ "'page' and 'size' (sort may be absent). Operations with x-spring-paginated explicitly set to "
340
+
+ "false will not be auto-detected. The legacy values 'true' (alias for 'page-size-sort') and "
341
+
+ "'false' (alias for 'none') are deprecated and will be removed in a future release.",
addSwitch(GENERATE_SORT_VALIDATION, "Generate a @ValidSort annotation and SortValidator class, and apply @ValidSort to the injected Pageable parameter of operations whose 'sort' parameter has enum values. The annotation validates that sort values in the Pageable object match the allowed enum values from the spec. Requires useBeanValidation=true and library is spring-boot or spring-cloud.", generateSortValidation);
318
344
addSwitch(GENERATE_PAGEABLE_CONSTRAINT_VALIDATION, "Generate a @ValidPageable annotation and PageableConstraintValidator class, and apply @ValidPageable to the injected Pageable parameter of operations whose 'page' or 'size' parameter specifies a maximum constraint. The annotation enforces those constraints on the Pageable object that replaces the individual page/size query parameters. Requires useBeanValidation=true and library is spring-boot or spring-cloud.", generatePageableConstraintValidation);
0 commit comments