Skip to content

[Java][Spring] Omit annotation attributes with default values - #25137

Open
ondrej-simon wants to merge 2 commits into
OpenAPITools:masterfrom
ondrej-simon:b/spring-redundant-annotation-attributes
Open

ondrej-simon wants to merge 2 commits into
OpenAPITools:masterfrom
ondrej-simon:b/spring-redundant-annotation-attributes

Conversation

@ondrej-simon

@ondrej-simon ondrej-simon commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #25136.

The spring generator emits annotation attributes that are equal to their defaults. This PR removes them, making the generated APIs leaner without changing their semantics:

  • required = true is no longer emitted on @RequestHeader, @RequestParam and @RequestPart (Spring's default is true); required = false is still emitted, consistent with how @CookieValue and @RequestBody are already generated. required = true on @Parameter is kept, as its default is false.
  • description on @Parameter is only emitted when present.
  • Empty operation and parameter descriptions are treated as absent in SpringCodegen, so specs with description: '' no longer produce @Operation(description = ""), @Parameter(description = "") or an empty * javadoc line. (jmustache treats "" as truthy in sections, so {{#notes}} alone is not enough.) This is done on the codegen models rather than with a global emptyStringIsFalse(true), which would also affect e.g. {{#defaultValue}}, where an explicit empty default is meaningful.

Before:

@NotNull @Parameter(name = "required_boolean_group", description = "Required Boolean in group parameters", required = true, in = ParameterIn.HEADER) @RequestHeader(value = "required_boolean_group", required = true) Boolean requiredBooleanGroup,
@Parameter(name = "api_key", description = "", in = ParameterIn.HEADER) @RequestHeader(value = "api_key", required = false) @Nullable String apiKey

After:

@NotNull @Parameter(name = "required_boolean_group", description = "Required Boolean in group parameters", required = true, in = ParameterIn.HEADER) @RequestHeader(value = "required_boolean_group") Boolean requiredBooleanGroup,
@Parameter(name = "api_key", in = ParameterIn.HEADER) @RequestHeader(value = "api_key", required = false) @Nullable String apiKey

While touching SpringCodegen#postProcessOperationsWithModels, I reduced its nesting with an early return and extracted the response post-processing and description cleanup into helpers. This refactoring is behavior-preserving: regenerating all Spring samples before and after it produces byte-identical output.

Changes:

  • JavaSpring/headerParams.mustache, queryParams.mustache, formParams.mustache, paramDoc.mustache
  • SpringCodegen: clear empty descriptions; early return/helpers in postProcessOperationsWithModels
  • SpringCodegenTest: new shouldOmitAnnotationAttributesWithDefaultValues, and updated 4 tests that asserted the old redundant attributes
  • Regenerated all spring and java-camel samples (73 configs). The sample diff only removes the attributes/lines listed above (verified with a script that every changed line differs only by these removals).

Tested: all Spring-related tests pass (SpringCodegenTest, JavaCamelServerCodegenTest, *Spring*Test, 800 tests).

PR checklist

  • Read the contribution guidelines.
  • Run the following to build the project and update samples:
    ./mvnw clean package || exit
    ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
    ./bin/utils/export_docs_generators.sh || exit
    
    (For Windows users, please run the script in WSL)
    Commit all changed files.
    This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
    These must match the expectations made by your contribution.
    You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
    IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
  • If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

cc Java Spring technical committee: @cachescrubber @welshm @MelleD @atextor @manedev79 @javisst @borsch @banlevente @Zomzog @martin-mfg @KannaKim


Summary by cubic

Fixes #25136 by omitting annotation attributes that equal Spring's defaults in generated Spring APIs, so generated code is leaner without changing semantics.

  • required = true is no longer emitted on @RequestHeader, @RequestParam, or @RequestPart; required = false is still emitted.
  • Empty operation and parameter descriptions are treated as absent, so description = "" no longer appears on @Operation or @Parameter, and no empty javadoc line is generated.

Refactor

  • SpringCodegen#postProcessOperationsWithModels uses an early return and helpers for response post-processing and description cleanup; behavior is preserved, verified by regenerating all Spring samples.
  • Also updates a stale go-oneof-not-enum sample to satisfy the samples up-to-date check.

Written for commit 241751d. Summary will update on new commits.

Review in cubic

Stop emitting attributes that equal their defaults in generated Spring APIs:
- required = true on @RequestHeader, @RequestParam and @RequestPart
- description = "" on @parameter and @operation (and the empty javadoc
  line), by treating empty operation/parameter descriptions as absent

Also simplify SpringCodegen#postProcessOperationsWithModels by using an
early return and extracting helpers.

Fixes OpenAPITools#25136

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 245 files

Note: This PR contains a large number of files. cubic selects up to 200 of the highest-priority eligible files for this review, so some files may not have been reviewed.

Re-trigger cubic

The sample on master is out of date after OpenAPITools#25064 and OpenAPITools#25089 were merged
concurrently, which fails the "Samples up-to-date" check.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 1 file (changes from recent commits).

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread samples/client/others/go/oneof-not-enum/docs/EnumNullUnion.md

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG][JAVA][Spring] Generated annotations contain attributes with default values (required = true, description = "")

1 participant