[spring] fix schema named "Schema" colliding with the swagger2 annotation

[GianniGiglio]

Fixes #16584

A schema named Schema generates a model that the generated code cannot reference.

AbstractJavaCodegen registers:

importMapping.put("Schema", "io.swagger.v3.oas.annotations.media.Schema");

and DefaultGenerator consults importMapping before toModelImport() (getAllImportsMappings, and the model path around DefaultGenerator:1794). The model import is therefore silently replaced by the annotation import, and the bare Schema type in api signatures binds to the annotation instead of the model:

import org.openapitools.model.BadRequest;
import org.openapitools.model.Error;
import io.swagger.v3.oas.annotations.media.Schema;   // <- substituted for the model import

default ResponseEntity<Schema> getSchema(...)                       // the annotation, not the model
@Content(schema = @Schema(implementation = Schema.class))           // self-referential

Emitting the model import instead does not fix it on its own: it then clashes with the annotation import the templates add, and in the model file with the declared class of the same name. Two single-type imports for the same simple name, and an import conflicting with a type declared in the same compilation unit, are both compile errors (JLS 7.5.1).

Change

• SpringCodegen.preprocessOpenAPI detects a model named Schema and drops the default importMapping entry so the model keeps the simple name. An explicit --import-mappings entry pointing at a different class is left untouched (covered by a test).
• The swagger2 annotation is then emitted fully qualified at its usage sites instead of imported, via two new template variables (swagger2SchemaAnnotation, importSwagger2SchemaAnnotation). This is confined to JavaSpring templates: api, apiController, model, pojo, lombokAnnotation.

The collision detection compares against toModelName(...), so modelNamePrefix/modelNameSuffix are honoured, and it runs after InlineModelResolver.flatten so inline-promoted models are covered.

Verification

Using the spec from the issue:

	result
master	BUILD FAILURE — 15 compile errors, e.g. org.openapitools.model.Schema is already defined in this compilation unit
this branch	BUILD SUCCESS

Verified for both interfaceOnly=true and the api controller variant.

• SpringCodegenTest: 339/339 pass.
• Regenerating all 71 spring* and java-camel* sample configs produces no diff — the qualification only applies when the collision is actually present, so existing output is byte-identical.

Note on the modified test

annotationLibraryDoesNotCauseImportConflictsInSpringWithAnnotationLibrary asserted that the model file contains import io.swagger.v3.oas.annotations.media.Schema;. Its spec (issue21991.yaml) names a schema Schema, so that assertion pins output that does not compile (the 15 errors above). It now asserts the fully-qualified form instead. Its sibling annotationLibraryDoesNotCauseImportConflictsInSpring (the annotationLibrary=none path fixed by #21992 / #22045) passes unchanged.

This completes the half that #21991 explicitly deferred — quoting that reporter:

This could also be presented as a different issue - "imports conflict with the model names", which would require significantly more effort to investigate and properly fix (figuring out which imports exactly might be conflicting and using fully-qualified class names all over the templates).

#21992 and #22045 fixed only the annotationLibrary=none path; the default swagger2 path, where the collision is unavoidable, is this issue.

Scope

Deliberately limited to the spring generator and the Schema key. AbstractJavaCodegen puts File, Date, Map, List, Set and UUID in the same map, so a model named File currently resolves to java.io.File — the same class of bug, but changing it means real behaviour changes and sample churn. Happy to widen this to AbstractJavaCodegen and the other Java generators (JavaClientCodegen and JavaJerseyServerCodegen call model.imports.add("Schema") and would need matching template work) if you'd prefer that in one pass.

---

Summary by cubic

Fixes the Spring generator so a schema named Schema generates code that compiles, instead of a model that cannot be referenced.

Bug Fixes

• Previously the model import was silently replaced by the io.swagger.v3.oas.annotations.media.Schema annotation import, so API signatures referenced the annotation instead of the model, and emitting both imports caused compile errors.
• The model now keeps the simple name Schema, and the swagger2 annotation is fully qualified at its usage sites in the Spring templates.
• An explicit --import-mappings entry for Schema pointing to a different class is left untouched.
• Existing output is unchanged when the collision is absent; regenerating all spring and java-camel samples produced no diff.

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

[cubic-dev-ai]

No issues found across 8 files

_{Re-trigger cubic}

[wing328]

thanks for the PR

cc @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)

[wing328]

a workaround is to rename the model to something else using the modelNameMappings option: https://github.com/OpenAPITools/openapi-generator/blob/master/docs/customization.md#name-mapping

[Mattias-Sehlstedt]

Would it make sense to break this check out into a more generic

handleSchemaNameCollision(String name, String import, String schemaKey, String importKey)

and then that you do

handleSchemaNameCollision("Schema", SWAGGER2_ANNOTATION_SCHEMA_IMPORT, SCHEMA_ANNOTATION, IMPORT_SCHEMA_ANNOTATION)

?
This should somewhat allow someone to fix this issue for similar issues, and it would also allow us to have a more generic description of the cause as javadoc on handleSchemaNameCollision rather than tying the description exactly to the reported scenario