fix(spring): avoid duplicate Tag import when a model is named Tag

[donald]

Fixes #24554

What

If the spec defines a model named Tag and an api uses it, the generated Spring api imported both the
model and io.swagger.v3.oas.annotations.tags.Tag. Two single-type-imports of the same simple name is a
hard javac error, so the generated code did not compile.

// before
import org.openapitools.model.Tag;                    // line 8
import io.swagger.v3.oas.annotations.tags.Tag;        // line 18
@Tag(name = "pets", description = "the pets API")
public interface TagApi {
    default ResponseEntity<Tag> getTag(...)

error: a type with the same simple name is already defined by the single-type-import of Tag

// after
import org.openapitools.model.Tag;
@io.swagger.v3.oas.annotations.tags.Tag(name = "pets", description = "the pets API")
public interface TagApi {
    default ResponseEntity<Tag> getTag(...)

This is not an ambiguity a wildcard import could resolve — both imports are explicit.

How

SpringCodegen.postProcessOperationsWithModels sets qualifySwaggerTagAnnotation when the file being
generated imports the model Tag; JavaSpring/api.mustache and JavaSpring/apiController.mustache then
emit the fully qualified annotation and skip the annotation import.

The model import is kept — it is the type actually used in the signatures.

Scoping matters here. My first attempt keyed off "the spec contains a model named Tag" and stored the
flag in additionalProperties. That is both too broad and sticky across files: the petstore sample defines
a Tag model, so every spring sample got the qualified annotation even though most api files never
import the model. It rewrote 171 sample files and broke testNoRequestMappingAnnotation and
testNoRequestMappingAnnotation_spring_cloud_default. The committed version checks
objs.getImports() for modelPackage() + ".Tag" and stores the flag per operations map, so only the files
that actually hit the clash change.

Testing

• SpringCodegenTest.modelNamedTagDoesNotClashWithSwaggerTagAnnotation — asserts the annotation import is
  gone, the annotation is fully qualified, and the model import is still present. Verified that this test
  fails without the fix.
• Full SpringCodegenTest (294 tests) passes, including the two cases the over-broad first attempt broke.
• Regenerated all 787 sample configs (./bin/generate-samples.sh ./bin/configs/*.yaml) and
  ./bin/utils/export_docs_generators.sh — no diff.

Note on the full test run: mvn test on modules/openapi-generator reports one pre-existing failure,
OpenApiSchemaValidationsTest.testNullTypeInOas31_noWarning. It fails identically on unmodified
master (4aed9c1c635) — verified by reverting the patch and re-running — and is unrelated to this change.

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
  

  Commit all changed files.
  (Both scripts were run; neither produced any change, so there is nothing to commit beyond the fix and its test.)
• File the PR against the correct branch: master
• 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 technical committee:
@bbdouglas @sreeshas @jfiala @lukoyanov @cbornet @jeff9finger @karismann @Zomzog @lwlee2608 @martin-mfg

🤖 Generated with Claude Code

---

Summary by cubic

Fixes a compile error in generated Spring APIs when a schema is named Tag by fully qualifying the Swagger @Tag annotation only in files that import the model Tag. This prevents duplicate single-type imports and restores compilation.

• Bug Fixes
  • Detect the clash per API file by checking for modelPackage.Tag imports and set qualifySwaggerTagAnnotation in SpringCodegen.postProcessOperationsWithModels.
  • In JavaSpring/api.mustache, render @io.swagger.v3.oas.annotations.tags.Tag and skip its import when flagged; in JavaSpring/apiController.mustache, skip the annotation import when flagged. Keep org.openapitools.model.Tag imported.
  • Added test modelNamedTagDoesNotClashWithSwaggerTagAnnotation; all Spring tests pass and regenerating samples shows no diff.

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

[cubic-dev-ai]

No issues found across 5 files

_{Re-trigger cubic}

[gs-covariance]

I actually have also hit this problem with the @Parameter annotation before. Do you think is there a way to make this more general?

Edit: Maybe a flag to use the full name for swagger annotations?

[donald]

@gs-covariance good point — @Parameter has exactly the same shape of problem, and so do @Operation, @Schema, @Content and friends. Any spec that happens to define a model with one of those names produces the same duplicate single-type-import.

I would rather not make it a flag, though, for two reasons:

• The user has to discover it first. The failure mode is a compile error in generated code, at which point the user has to work out that a swagger annotation name collides with one of their model names and that a flag exists to work around it. The collision is fully detectable at generation time, so the generator can just do the right thing.
• A global "fully qualify all swagger annotations" switch would churn every generated api file for everyone who turns it on, including the vast majority of files that have no collision at all. That is the same over-broad behaviour I had to narrow down in this PR (my first attempt keyed off "the spec contains a model named Tag" and rewrote 171 sample files before being scoped to the files that actually import the model).

The direction I would suggest instead is to generalise the detection, not add a switch: keep a map of simple name -> fully qualified swagger annotation for the annotations the templates emit, and for each api file qualify exactly those whose simple name is imported as a model. Zero configuration, and files without a collision stay byte-identical.

That is a bigger change than this bug fix, so I would prefer to keep this PR narrow (it unbreaks Tag, which is the one that shows up in the petstore spec) and do the generalisation as a follow-up. Happy to open an issue for it, or to fold it in here if maintainers would rather have it in one go — @bbdouglas @cbornet @martin-mfg any preference?