[JAVA-SPRING;KOTLIN-SPRING] feature: x-field-extra-annotation parity for kotlin-spring params + new x-request-body-extra-annotation + --inject-operation-vendor-extensions

[Picazsoo]

Summary

Adds custom-annotation support for previously uncovered spots in the Spring generators:

1. x-field-extra-annotation on kotlin-spring path/query/form/header params: brings kotlin-spring
   to parity with java-spring, which already renders this extension on parameters.
2. New operation-level x-request-body-extra-annotation (java-spring and kotlin-spring):
   lets you attach annotations to the generated request-body parameter, even when the body $refs a
   shared model.
3. x-field-extra-annotation on cookie params (java-spring and kotlin-spring): closes the
   last parameter kind that supported it in neither generator.
4. New --inject-operation-vendor-extensions CLI/config flag (all generators): injects vendor
   extensions onto operations and their parameters from the command line or config, without editing
   the spec. This complements the existing --inject-model-vendor-extensions flag and is the natural
   way to apply the two extensions above when you cannot or do not want to touch the source contract.

Both accept a string or a list of strings, are applied per operation (selective), and are a
no-op when absent.

Motivation

Users commonly reference reusable ID/model schemas from many operations:

components:
  schemas:
    OrgId: { type: string, format: uuid }
    Employee: { ... }

To add a validation/framework annotation to a specific usage (e.g. Hibernate Validator / LSP rules
that require constraints to live on the generated interface, not the impl), you need a placement that
is both ref-safe and per-operation:

• Path / query / form / header / cookie params support two placements, and you can pick based
  on the scope you want:

  • On the shared schema (for example on OrgId): applies globally to every parameter that
    $refs that schema. Use this when the annotation should always accompany the type. The generator
    already merges a referenced parameter schema's extensions onto the parameter, so this works for
    the simple alias schemas typically used by parameters.
  • On the Parameter Object (sibling of name/in): applies selectively to that single
    usage, and keeps the shared schema: { $ref: ... } clean and reusable for other operations. Use
    this when only some usages should carry the annotation.
  • Previously java-spring rendered the annotation on path/query/form/header params but not cookie,
    while kotlin-spring rendered it on none of them. Parts 1 and 3 close those gaps so every parameter
    kind behaves consistently in both generators.

• Request bodies usually $ref a shared model, so there is no per-usage object to annotate:

  • keys placed next to a $ref are ignored (OpenAPI 3.0/3.1),
  • annotating the referenced model applies globally to every operation.

  Part 2 solves this with an operation-level extension: operations are never $ref targets, so
  the annotation is inherently per-usage and ref-safe.

Example (Part 1: parameter object)

parameters:
  - name: orgId
    in: path
    required: true
    x-field-extra-annotation: "@com.example.ValidOrgId"   # on the parameter object
    schema:
      $ref: '#/components/schemas/OrgId'                   # ref stays clean/reusable

Example (Part 2: request body)

paths:
  /employees:
    post:
      x-request-body-extra-annotation: "@com.example.MyValidation"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Employee'

Generates (java-spring):

ResponseEntity<Void> createEmployee(
    @com.example.MyValidation @Valid @RequestBody Employee employee
) { ... }

Request-body annotation placements (three working scopes)

Besides the new operation-level extension, the body param also honors annotations declared on the
RequestBody Object itself (these are merged onto the generated body parameter). This gives three
placements, chosen by the scope you want:

1. Operation-level x-request-body-extra-annotation (the new extension): per operation. Works
   even when the operation's requestBody is a bare $ref.
2. Inline requestBody object x-field-extra-annotation: per operation.

   requestBody:
     x-field-extra-annotation: "@com.example.InlineBodyValidation"
     content: { application/json: { schema: { $ref: '#/components/schemas/Employee' } } }

3. Reusable components.requestBodies object x-field-extra-annotation: applies to every
   operation that $refs that reusable request body (a shared subset).

   components:
     requestBodies:
       AnnotatedEmployeeBody:
         x-field-extra-annotation: "@com.example.ReusableBodyValidation"
         content: { application/json: { schema: { $ref: '#/components/schemas/Employee' } } }

Caveat: a key placed as a sibling of $ref in the operation's requestBody is ignored (OpenAPI
3.0/3.1), so to annotate a $ref-ed reusable body the extension must live inside the reusable
components.requestBodies object (option 3), not next to the $ref.

Example (injecting the extensions from the CLI, no spec edit)

When you cannot modify the source contract, the same result is achievable via
--inject-operation-vendor-extensions:

openapi-generator generate -g spring -i api.yaml -o out \
  --inject-operation-vendor-extensions \
      "createEmployee.x-request-body-extra-annotation=@com.example.MyValidation" \
  --inject-operation-vendor-extensions \
      "createEmployee.orgId.x-field-extra-annotation=@com.example.ValidOrgId"

Key formats:

• operationId.x-extension-name=value targets the operation (for example the request-body
  extension above).
• operationId.paramBaseName.x-extension-name=value targets a parameter, matched by its spec
  name (baseName). The operationId segment is matched against the spec-authored operationId when
  present, falling back to the generated operationId only when the spec omits one.

Changes

New extension & wiring

• VendorExtension: added X_REQUEST_BODY_EXTRA_ANNOTATION (OPERATION level).
• Registered in getSupportedVendorExtensions() for both spring and kotlin-spring.
• DefaultCodegen: new shared helper mergeOperationVendorExtensionIntoBodyParams(...) that copies
  the operation-level values onto the body parameter's x-field-extra-annotation list, so both
  extensions render through the existing body-param template path.
• Normalization (string-or-list → List<String>) applied in both SpringCodegen and
  KotlinSpringServerCodegen (the latter gains a small parameter-normalization helper, since it does
  not share the Java generator's base class).

Vendor-extension injection flag (all generators)

• New --inject-operation-vendor-extensions CLI option (repeatable) plus the matching
  CodegenConfigurator.addInjectOperationVendorExtension / GeneratorSettings wiring, mirroring the
  existing --inject-model-vendor-extensions plumbing.
• Injection is applied in DefaultCodegen.fromOperation, so it runs for every generator and before
  generator-specific post-processing. This means an injected x-request-body-extra-annotation flows
  through the same normalize-and-merge path as one declared in the spec.

Templates

• kotlin-spring pathParams / queryParams / formParams / headerParams: render
  x-field-extra-annotation before the parameter binding (java-spring parity).
• java-spring & kotlin-spring cookieParams: render x-field-extra-annotation before @CookieValue
  / the cookie binding (previously unsupported in both).
• java-spring & kotlin-spring bodyParams: render the merged annotation before @RequestBody /
  the body binding. Covers useOptional and reactive (Mono/Flux, Flow/suspend) variants.
• Header and cookie params required no generator-code change: both generators already normalize those
  parameter collections to List<String>, so only the templates were missing.

Samples (compile-verified)

• To exercise the features in real, compiled samples without adding slow new build targets, the two
  shared petstore specs were copied and the copies annotated:
  petstore-with-fake-endpoints-models-for-testing-extra-annotation.yaml (java) and
  3_0/kotlin/petstore-with-extra-annotation.yaml (kotlin). The originals are untouched, so there is
  no ripple to the 140+ other configs that consume them.
• Four existing samples were repointed to the copies, covering both generators across reactive and
  non-reactive: springboot-useoptional (java, useOptional), springboot-reactive (java,
  Mono/Flux), kotlin-springboot-delegate (kotlin), and kotlin-springboot-reactive (kotlin,
  Flow/suspend). All four compile locally.
• The annotated copies demonstrate: operation-level x-request-body-extra-annotation on addPet
  (a $ref body) with updatePet left un-annotated (selectivity); param x-field-extra-annotation
  on a path, a list-valued query, and a form param; and, on the kotlin copy, x-extra-imports so the
  annotations are referenced by short name.
• The same four samples also exercise the --inject-operation-vendor-extensions side-loading path
  (expressed as an injectOperationVendorExtensions: block in each sample config, the config-file
  equivalent of the CLI flag). Without editing the spec, they inject an operation-level
  x-request-body-extra-annotation onto placeOrder and a parameter-level x-field-extra-annotation
  onto the getOrderById path param. Because the java base spec names that param order_id while the
  kotlin base spec names it orderId, the two configs use different keys, which validates that the
  parameter segment is matched against the raw spec paramBaseName. On the kotlin samples the configs
  also side-load x-extra-imports next to the injected annotations, so the injected @NonNull is
  imported and referenced by short name (the java samples keep the fully-qualified form, since
  java-spring has no x-extra-imports support). The injected annotations render and compile alongside
  the spec-declared ones.

Docs

• Regenerated docs/generators/spring.md and docs/generators/kotlin-spring.md (vendor-extension
  tables) via the docs task, not hand-edited. (No table change for the header/cookie additions, which
  reuse the existing x-field-extra-annotation.)

Tests

• java-spring: request-body annotation with a $ref body + a second operation on the same model
  without the extension (proves selectivity); covers a non-default body branch. Cookie-param
  coverage added to the existing parameter-annotation test.
• kotlin-spring: x-field-extra-annotation on path/query/form/header/cookie params (incl.
  list-valued cases), plus request-body annotation with selectivity.
• injection flag: unit test in DefaultCodegenTest (operation-level and parameter-level landing,
  non-matching operationId is a no-op) plus java-spring and kotlin-spring end-to-end tests that inject
  both extensions and assert selective rendering.
• request-body placements: the java-spring and kotlin-spring request-body tests also assert that an
  x-field-extra-annotation declared on the inline requestBody object and on a reusable
  components.requestBodies object (referenced by two operations) render on the body param.

Design notes / trade-offs

• Merge into x-field-extra-annotation instead of a new template branch. The operation-level
  request-body value is merged onto the body parameter's existing annotation list, so rendering
  reuses one code path and multiple annotations compose naturally. Existing param-level annotations
  are preserved and appear first.
• Values normalized to List<String>. A single string and a list are handled uniformly, extra
  values can be appended, and an absent extension yields an empty list → renders nothing (no change
  when unused).
• The param extension supports both schema-level and Parameter Object placement. Placing it on
  the shared schema applies it globally to every usage of that schema; placing it on the Parameter
  Object applies it selectively to a single usage and keeps the shared $ref reusable. Both are
  valid; choose based on whether you want global or per-usage scope.

Known limitation (out of scope)

If a requestBody declares different schemas per content type, the generator still models it as a
single body parameter / single @RequestBody argument (Spring itself binds one body per method),
so the annotation applies to that one binding, and it cannot be varied per content type. Generating one
method per content type (via consumes dispatch) would be the fully spec-faithful approach but is a
broader change (it breaks the 1:1 operation→method contract across all generators) and is not
addressed here. The operation-level design does not preclude adding a media-type-level extension
later if that path is ever taken.

Acceptance

• kotlin-spring renders x-field-extra-annotation on path/query/form/header params (java-spring
  parity), including list values; model-field behavior unchanged.
• x-field-extra-annotation renders on cookie params in both java-spring and kotlin-spring.
• x-request-body-extra-annotation renders before the body param in java-spring and kotlin-spring,
  works with $ref bodies, is selective per operation, and covers useOptional / reactive variants.
• Both extensions accept a string or a list of strings; absent extension = no change.
• --inject-operation-vendor-extensions applies operation- and parameter-level extensions from the
  CLI/config for any generator, selectively per operation, with an empty/absent map being a no-op.
• Docs regenerated; new tests pass with no regressions.
• Four existing samples (java + kotlin, reactive + non-reactive) were repointed to annotated copies
  of the shared petstore specs and compile with the emitted annotations, verifying the feature
  end-to-end without adding new build targets. The same samples also inject both extensions via an
  injectOperationVendorExtensions: config block (the side-loading path), confirming the CLI/config
  injection mechanism renders and compiles too.

Plugin parity (Gradle + Maven)

The injectModelVendorExtensions / injectOperationVendorExtensions side-loading maps were only
reachable from the plugins through a configFile. They are now first-class properties on both the
Gradle and Maven plugins, matching the CLI and the existing parity of the other mapping properties
(nameMappings, globalProperties, etc.):

• Gradle (openApiGenerate { ... }): two MapProperty<String, String> fields wired through the
  extension, plugin, and GenerateTask to the configurator.
• Maven (<configuration>): two List<String> KVP parameters
  (openapi.generator.maven.plugin.inject{Model,Operation}VendorExtensions) applied via the shared
  applyInject*KvpList helpers. These settings are configurator-level (not generator CliOptions)
  and have no configOptions backwards-compat reader, so unlike the legacy mapping options they need
  no configOptions guard; the same review also removed the equally dead configOptions guards from
  the five *-name-mappings parameters (the inline-schema-options guard is kept, since it does have
  a compat reader).
• Docs: added to the Gradle README.adoc and Maven README.md config tables. The CLI help for
  --inject-*-vendor-extensions now clarifies that multiple annotations in a single value are
  space-separated (emitted verbatim into source); an unquoted comma is the separator between
  different injection targets, so comma-bearing annotation attributes should use the spec-level
  extension (string or YAML list) instead.
• Tests: a Gradle ParameterWiringRegressionTest case asserts the injected annotation reaches
  generated sources, and a Maven CodeGenMojoTest case (new inject-vendor-extensions resource
  project) asserts the injected x-request-body-extra-annotation is merged onto the body parameter
  and rendered on the generated Spring API.

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.

[cubic-dev-ai]

All reported issues were addressed across 27 files

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

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 29 files

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

Re-trigger cubic</sub>

[Picazsoo]

@cubic-dev-ai, please re-review

[cubic-dev-ai]

@cubic-dev-ai, please re-review

@Picazsoo I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

All reported issues were addressed across 56 files

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

Re-trigger cubic</sub>

[cubic-dev-ai]

No issues found across 56 files

_{Re-trigger cubic}

[cubic-dev-ai]

No issues found across 56 files

_{Re-trigger cubic}