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

Fechada
  • Algo errado?
#3,398 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
57/100
Tipo de issue
Bug
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
java, openapi, spring-boot
Domínio
backend-api-design

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
Java
Estrelas
3.7k
Forks
605
Merge médio
3d 15h
PRs com merge (30d)
19

Preparar o ambiente

Este projeto não oferece contêiner de desenvolvimento, Dockerfile nem guia de contribuição, então a configuração fica por sua conta: comece pelo README e veja nosso guia da primeira contribuição para os passos gerais.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de springdoc/springdoc-openapi

Todas as issues de springdoc/springdoc-openapi

Issues semelhantes

Mais issues de Java

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.