[Java][Spring] Annotate deprecated fluent model setters with @Deprecated

[kalayciburak]

The Java Spring generator already annotates fields, getters, regular setters, and nested builder methods for properties marked deprecated: true. Fluent model setters and collection helpers (addXItem / putXItem) were missing @Deprecated.

This updates JavaSpring/pojo.mustache so those methods emit @Deprecated as well, including inherited fluent helpers.

Fixes #24704

PR checklist

• Read the contribution guidelines.
• Ran the following to build the project and update samples:

  ./mvnw -pl modules/openapi-generator-cli -am package -DskipTests=true -Dmaven.javadoc.skip=true -Djacoco.skip=true
  ./bin/generate-samples.sh ./bin/configs/spring*.yaml
  

  Regenerated Spring samples only. The sample delta is @Deprecated on fluent setters and collection helpers for already-deprecated properties (for example Pet.status).
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

Java Spring @cachescrubber (2022/02) @welshm (2022/02) @MelleD (2022/02) @atextor (2022/02) @manedev79 (2022/02) @javisst (2022/02) @borsch (2022/02) @banlevente (2022/02) @Zomzog (2022/09) @martin-mfg (2023/08) @KannaKim (2026/07)

Tests

Executed:

• ./mvnw -pl modules/openapi-generator -am test -Dtest=SpringCodegenTest#contractWithDeprecatedPropertiesAnnotatesFluentSettersAndCollectionHelpers RED then GREEN
• ./mvnw -pl modules/openapi-generator -am test -Dtest=SpringCodegenTest#contractWithDeprecatedEnumGeneratesDeprecatedAnnotation,SpringCodegenTest#contractWithDeprecatedPropertiesAnnotatesFluentSettersAndCollectionHelpers,SpringCodegenTest#shouldGenerateSingleDeprecatedAnnotation 3/3 GREEN

---

Summary by cubic

Annotates Java Spring generated fluent setters and collection helpers for deprecated properties with both @deprecated and @deprecated Javadoc to match existing deprecation on fields/getters/setters/builder methods. Previously these methods had no deprecation markers; now they do, including inherited helpers, to surface consistent IDE/compiler warnings.

• Template change: updates modules/openapi-generator/src/main/resources/JavaSpring/pojo.mustache to emit @Deprecated and @deprecated Javadoc on fluent setters (prop(value)), addXItem(...), putXItem(...), and inherited equivalents when the schema property has deprecated: true.
• Tests and samples: adds src/test/resources/3_0/spring/issue_24704.yaml and a test asserting both the annotation and Javadoc; regenerates Spring samples to reflect the new markers.
• Impact: No runtime change. Calls to these fluent methods may now produce deprecation warnings. No migration required; prefer non-deprecated properties or suppress warnings.

^{Written for commit 0cbc581. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 50 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[wing328]

thanks for the PR

can you please review the feedback in #24705 (comment) ?

[kalayciburak]

yep, added the javadoc tag on fluent setters too

[cubic-dev-ai]

1 issue found across 49 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/client/petstore/spring-cloud-deprecated/src/main/java/org/openapitools/model/Pet.java">

<violation number="1" location="samples/client/petstore/spring-cloud-deprecated/src/main/java/org/openapitools/model/Pet.java:165">
P3: The `@deprecated` javadoc tag is emitted with no description text, so javadoc builds of the generated code emit the warning `@deprecated tag has no <Text>` and users get no guidance on what to use instead. Add the replacement guidance in the tag, e.g. `* @deprecated Use {@link #getPhotoUrls()} instead`, matching the `@Deprecated` indication.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The @deprecated javadoc tag is emitted with no description text, so javadoc builds of the generated code emit the warning @deprecated tag has no <Text> and users get no guidance on what to use instead. Add the replacement guidance in the tag, e.g. * @deprecated Use {@link #getPhotoUrls()} instead, matching the @Deprecated indication.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/spring-cloud-deprecated/src/main/java/org/openapitools/model/Pet.java, line 165:

<comment>The `@deprecated` javadoc tag is emitted with no description text, so javadoc builds of the generated code emit the warning `@deprecated tag has no <Text>` and users get no guidance on what to use instead. Add the replacement guidance in the tag, e.g. `* @deprecated Use {@link #getPhotoUrls()} instead`, matching the `@Deprecated` indication.</comment>

<file context>
@@ -161,12 +161,18 @@ public void setName(JsonNullable<String> name) {
   }
 
+  /**
+   * @deprecated
+   */
   @Deprecated
</file context>