Property-level @Schema(oneOf) makes every other property of the same type lose its subtypes (static TYPES_TO_SKIP)

Geschlossen
  • Stimmt etwas nicht?
#3,398 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 9 Tagen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
57/100
Issue-Typ
Bug
Klarheit
Klar beschrieben
Aktivitätsstatus
Aktiv
Tech-Stack
java, openapi, spring-boot
Bereich
backend-api-design

Rechercherichtung

Start by reading PolymorphicModelConverter and tracing how TYPES_TO_SKIP affects composePolymorphicSchema when properties are resolved. Reproduce the reported case with the supplied Spring Boot example and inspect GET /v3/api-docs. Done means only the property declaring @Schema(oneOf) is narrowed, while the plain properties still include both Circle and Square.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

An AI coding agent (Claude Code) found this bug while working in our codebase, traced it to PolymorphicModelConverter, reproduced it in a bare Spring Boot app and wrote this issue. The results below come from that app, not from reading the code alone.

Describe the bug

When one property declares @Schema(oneOf = ...) (or allOf), PolymorphicModelConverter adds the simple name of the property's type to the static set TYPES_TO_SKIP. composePolymorphicSchema then gives no subtypes to every later property of that type, in every class, for the rest of the JVM. Such a property is written as {} (abstract parent) or as a oneOf with only the parent (concrete parent).

Issue #2851 asked for the declared types to win on the field that declares them. The skip now also applies to other fields that declare nothing. The result depends on the order in which the schemas are resolved: in our application, removing an unrelated request body from one endpoint emptied a List<FileDTO> property elsewhere in the spec.

To Reproduce

  • springdoc-openapi-starter-webmvc-api 3.2.0 (also 3.1.1), Spring Boot 4.1.2, Java 25, default settings
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "kind")
@JsonSubTypes({ @JsonSubTypes.Type(value = Circle.class, name = "CIRCLE"),
                @JsonSubTypes.Type(value = Square.class, name = "SQUARE") })
public abstract static class Shape {}
public static class Circle extends Shape { public double radius; }
public static class Square extends Shape { public double side; }

public static class NarrowedHolder {
    @Schema(oneOf = Circle.class)
    public Shape shape;
}
public static class PlainHolder {
    public Shape shape;
}
public static class Outer {
    public NarrowedHolder first;
    public PlainHolder second;
}

@RestController
public static class OuterController {
    @PostMapping("/outer")
    public void outer(@RequestBody Outer body) {}
}

GET /v3/api-docs, then components.schemas:

  • NarrowedHolder.shape: {"oneOf":[{"$ref":"#/components/schemas/Circle"}]} (correct)
  • PlainHolder.shape: {}

With only @PostMapping("/plain") void plain(@RequestBody PlainHolder body), PlainHolder.shape is {"oneOf":[Circle, Square]}.

The same happens inside one class:

public static class BothHolder {
    @Schema(oneOf = Circle.class)
    public Shape narrowed;
    public Shape plain;     // written as {}
}

Expected behavior

PlainHolder.shape and BothHolder.plain are oneOf Circle and Square. Only the property that declares oneOf gets the declared subtypes.

Cause

TYPES_TO_SKIP is static, keyed on the simple class name, and never cleared. The decision should belong to the property that is resolved. Note that in OpenAPI 3.1 mode swagger-core removes @Schema from the ctxAnnotations of a property (SiblingAnnotationFilter), so the converter cannot read it there. We work around it in our project: while the converter resolves a type, it keeps the names of that type's properties that declare oneOf/allOf, and it checks AnnotatedType#getPropertyName() against them when it resolves a property of that type.

Vorherrschende Sprache
Java
Sterne
3.7k
Forks
605
Ø Merge
9 T. 11 Std.
Gemergte PRs (30 T.)
14

Entwicklungsumgebung

Dieses Projekt bietet weder Dev-Container noch Dockerfile noch Beitragsleitfaden – die Einrichtung liegt bei Ihnen. Beginnen Sie mit der README; die allgemeinen Schritte stehen in unserem Leitfaden für den ersten Beitrag.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus springdoc/springdoc-openapi

Alle Issues in springdoc/springdoc-openapi

Ähnliche Issues

Weitere Issues zu Java

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.