fix: normalize Java annotation vendor extension lists

[wilx]

Continuation of #23750.

This keeps the original fix for x-class-extra-annotation and addresses the review feedback by:

• moving string/list normalization into a reusable shared helper
• applying normalization to Java/Spring class, field/parameter, and operation annotation vendor extensions
• preserving backward compatibility for scalar strings, block scalar strings, one-element lists, and multi-element lists
• merging duplicate tests and using supportedLibraries coverage for Java client model annotations
• adding Spring coverage for class, field, operation, and parameter annotations
• updating vendor extension descriptions and generated generator docs

Focused test run:

./mvnw -pl modules/openapi-generator -am   -Dtest=JavaClientCodegenTest#testAllOfClassWithAnnotations,SpringCodegenTest#testAllOfClassWithAnnotations   -Dsurefire.failIfNoSpecifiedTests=false test

Also regenerated the affected Spring oneOf samples to confirm no generated sample diff remains.

---

Summary by cubic

Normalize Java annotation vendor extensions so x-class-extra-annotation, x-field-extra-annotation, and x-operation-extra-annotation accept a string or a list and each annotation is rendered on its own line. Applies across Java and Spring generators for models, properties/parameters, and operations.

• Bug Fixes
  • Added DefaultCodegen.normalizeVendorExtensionWithStringList and used it in AbstractJavaCodegen and SpringCodegen; preserves single strings, block scalars, and lists. Also applied to x-implements.
  • Normalize x-class-extra-annotation on models and x-field-extra-annotation on all model properties; normalize x-field-extra-annotation on all operation parameters.
  • In Spring, normalize x-operation-extra-annotation on operations and parameter annotations.
  • Updated mustache templates to iterate and emit each annotation line.
  • Updated generator docs to state accepted types; added tests covering Java libraries and Spring for class, property, operation, and parameter annotations.

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

[cubic-dev-ai]

5 issues found and verified against the latest diff

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="docs/generators/java-vertx-web.md">

<violation number="1" location="docs/generators/java-vertx-web.md:87">
P2: java-vertx-web generator docs advertise string/list support for `x-class-extra-annotation` and `x-field-extra-annotation`, but the generator's Mustache templates never render these vendor extensions</violation>

<violation number="2" location="docs/generators/java-vertx-web.md:88">
P2: `x-field-extra-annotation` description only mentions 'property' despite being applicable to both `FIELD` and `OPERATION_PARAMETER`. The description should mention both targets to match the applicability column and avoid confusing users about operation-parameter support.</violation>
</file>

<file name="docs/generators/java-undertow-server.md">

<violation number="1" location="docs/generators/java-undertow-server.md:88">
P2: `x-field-extra-annotation` description only mentions 'property' but the extension also applies to `OPERATION_PARAMETER`</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: x-field-extra-annotation description only mentions 'property' despite being applicable to both FIELD and OPERATION_PARAMETER. The description should mention both targets to match the applicability column and avoid confusing users about operation-parameter support.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/generators/java-vertx-web.md, line 88:

<comment>`x-field-extra-annotation` description only mentions 'property' despite being applicable to both `FIELD` and `OPERATION_PARAMETER`. The description should mention both targets to match the applicability column and avoid confusing users about operation-parameter support.</comment>

<file context>
@@ -84,8 +84,8 @@ These options may be applied as additional-properties (cli) or configOptions (pl
-|x-class-extra-annotation|List of custom annotations to be added to model|MODEL|null
-|x-field-extra-annotation|List of custom annotations to be added to property|FIELD, OPERATION_PARAMETER|null
+|x-class-extra-annotation|Custom annotation(s) to be added to model; accepts a string or list of strings|MODEL|null
+|x-field-extra-annotation|Custom annotation(s) to be added to property; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null
 
 
</file context>

Suggested change

	|x-field-extra-annotation|Custom annotation(s) to be added to property; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null
	|x-field-extra-annotation|Custom annotation(s) to be added to property or operation parameter; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null

[cubic-dev-ai]

P2: java-vertx-web generator docs advertise string/list support for x-class-extra-annotation and x-field-extra-annotation, but the generator's Mustache templates never render these vendor extensions

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/generators/java-vertx-web.md, line 87:

<comment>java-vertx-web generator docs advertise string/list support for `x-class-extra-annotation` and `x-field-extra-annotation`, but the generator's Mustache templates never render these vendor extensions</comment>

<file context>
@@ -84,8 +84,8 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |x-content-type|Specify custom value for 'Content-Type' header for operation|OPERATION|null
-|x-class-extra-annotation|List of custom annotations to be added to model|MODEL|null
-|x-field-extra-annotation|List of custom annotations to be added to property|FIELD, OPERATION_PARAMETER|null
+|x-class-extra-annotation|Custom annotation(s) to be added to model; accepts a string or list of strings|MODEL|null
+|x-field-extra-annotation|Custom annotation(s) to be added to property; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null
 
</file context>

[wilx]

Again, pre-existing issue worth fixing as a separate PR.

[cubic-dev-ai]

P2: x-field-extra-annotation description only mentions 'property' but the extension also applies to OPERATION_PARAMETER

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/generators/java-undertow-server.md, line 88:

<comment>`x-field-extra-annotation` description only mentions 'property' but the extension also applies to `OPERATION_PARAMETER`</comment>

<file context>
@@ -84,8 +84,8 @@ These options may be applied as additional-properties (cli) or configOptions (pl
-|x-class-extra-annotation|List of custom annotations to be added to model|MODEL|null
-|x-field-extra-annotation|List of custom annotations to be added to property|FIELD, OPERATION_PARAMETER|null
+|x-class-extra-annotation|Custom annotation(s) to be added to model; accepts a string or list of strings|MODEL|null
+|x-field-extra-annotation|Custom annotation(s) to be added to property; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null
 
 
</file context>

Suggested change

	|x-field-extra-annotation|Custom annotation(s) to be added to property; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null
	|x-field-extra-annotation|Custom annotation(s) to be added to property or operation parameter; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null