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

Fermée
  • Quelque chose ne va pas ?
#3,398 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
57/100
Type d'issue
Bug
Clarté
Clairement spécifiée
Activité
Active
Stack technique
java, openapi, spring-boot
Domaine
backend-api-design

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
Java
Étoiles
3.7k
Forks
605
Merge moyen
4 j 18 h
PR mergées (30 j)
21

Préparer son environnement

Ce projet ne fournit ni conteneur de développement, ni Dockerfile, ni guide de contribution : l'installation est à votre charge. Commencez par son README, et consultez notre guide de la première contribution pour les étapes générales.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de springdoc/springdoc-openapi

Toutes les issues de springdoc/springdoc-openapi

Issues similaires

Plus d'issues Java

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.