feat(spring): add x-items-extra-annotation vendor extension for collection items

[adraarda23]

Introduces a new field-level OpenAPI vendor extension x-items-extra-annotation that places a custom type-use annotation on the type argument of Java collections (List, Set) generated by the Spring server generator, enabling per-element bean validation constraints such as @NotNull. The extension is set on the array property itself; the generated POJO field, getter, setter and fluent builder all use the annotated parameterized type, e.g.:

private List<@jakarta.validation.constraints.NotNull Stubb> sample;

The implementation precomputes the full datatype string in SpringCodegen#postProcessModelProperty and exposes it via x-datatype-with-items-annotation on the property; a small mustache partial (dataTypeWithItemsAnnotation) then renders that string or falls back to {{datatypeWithEnum}}, so existing models without the extension produce byte-identical output. The wrap is also propagated through JsonNullable<...> for nullable containers. When uniqueItems: true is set, Set is used instead of List. Map / additionalProperties is intentionally not covered by this extension.

Scoped to the Spring generator on purpose: the issue author's reference attempt was on JavaSpring/pojo.mustache and Spring has no library overrides for that template, so coverage is complete here. Other Java and JaxRS generators have library-specific pojo overrides that would each need to be wired up separately; that can be added in a follow-up if requested.

Fixes #23705

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work.
• 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
  

• File the PR against the correct branch: master
• If your PR solves a reported issue, reference it using GitHub's linking syntax
• If your PR is targeting a particular programming language, @mention the technical committee members

[cubic-dev-ai]

1 issue found across 10 files

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/spring.md">

<violation number="1" location="docs/generators/spring.md:147">
P2: The docs say `x-inner-validation` is a FIELD extension, but Spring only reads it from array/set `items`, so the placement is misleading.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[jpfinne]

@adraarda23 The allOf does not seem intuitive.

Could you use this syntax ?

listSample:
  type: array
  x-inner-validation: '@jakarta.validation.constraints.NotNull'
  items:  
     $ref: '#/components/schemas/Stubb'

And I would call that x-item-validation

[jpfinne]

@adraarda23 I've changed my mind...
The inner annotation can be used for validation, conversion, documentation....
So what about using similar to the x-xxx-extra-annoation?

listSample:
  type: array
  x-field-extra-annotation: '@jakarta.validation.Size(min=1, max=10)'
  x-inner-extra-annotation: '@jakarta.validation.constraints.NotNull'
  items:  
     $ref: '#/components/schemas/Stubb'

generating:
@jakarta.validation.Size(min=1, max=10) List<@jakarta.validation.constraints.NotNull Stubb> listSample;

[adraarda23]

@jpfinne how about x-items-extra-annotation ? How does it sound ?

[Chrimle]

Isn't this a Type-annotation? So, x-type-extra-annotation? 🤔

[jpfinne]

Isn't this a Type-annotation? So, x-type-extra-annotation? 🤔

Not a good idea.

List is also a type. How to understand that it is not the same as x-field-extra-annotation?