Subtype loses allOf reference to its polymorphic parent since 3.2.0 when a controller repeats the interface's @Valid on a @RequestBody

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

Mantenedores costumam responder em até 1 dia

@jochenberger já está trabalhando nisso.

Desde 27/10/2026.

  • #3394 de @jochenberger — aberto

Avaliação

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

Direção de pesquisa

Start in GenericParameterService.resolveTypeAndTypeAnnotationsForParameter, where annotations of the parameter's AnnotatedType were added in ada02a095, and compare with DelegatingMethodParameter.getTypeUseAnnotations. The proposed filter is to drop type-use annotations already present among the parameter annotations, so the context-annotation cache key for createCat matches updateCat again. Reproduce first with the attached test.org.springdoc.api.v31.app283 fixture in springdoc-openapi-starter-webmvc-api, asserting Cat is emitted as allOf with a $ref to Animal. Note an open pull request already exists, so coordinate before starting.

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

Descrição

Describe the bug

After upgrading from 3.1.1 to 3.2.0, subtypes of a @JsonSubTypes parent are documented as flat object schemas instead of allOf: [{$ref: Parent}, {…}]. If all subtypes are affected, the parent schema is then unreferenced and removed by removeBrokenReferenceDefinitions (with springdoc.remove-broken-reference-definitions=false it is still there, but nothing references it).

The trigger is a controller method that implements an interface method and repeats the interface's @Valid on the @RequestBody parameter:

interface CatApi {
	@PostMapping("/cats")
	void createCat(@Valid @RequestBody Cat cat);
}

@RestController
public class HelloController implements CatApi {
	@Override
	public void createCat(@Valid Cat cat) { } // removing @Valid here restores the 3.1.1 output
}

To Reproduce

  • Spring Boot: 4.1.1
  • springdoc-openapi: springdoc-openapi-starter-webmvc-ui 3.2.0 (works with 3.1.1)
  • swagger-core: 2.2.55 (same in both versions)
  • springdoc.api-docs.version=OPENAPI_3_1

A test case for springdoc-openapi-starter-webmvc-api is attached (test.org.springdoc.api.v31.app283, two files). HelloController contains:

  • Animal: abstract, @JsonSubTypes(Cat), and its subtype Cat
  • CatApi: PUT /cats and POST /cats, both with @Valid @RequestBody Cat; POST /cats also declares @ApiResponse(content = @Content(schema = @Schema(implementation = Cat.class)))
  • updateCat without parameter annotations, createCat repeating @Valid
  • POST /pets with @RequestBody Animal and GET /cats/count returning a String

Expected behavior

"Cat": {
  "allOf": [
    { "$ref": "#/components/schemas/Animal" },
    { "type": "object", "properties": { "indoor": { "type": "boolean" } } }
  ]
}

Actual behavior

Cat is a flat object schema containing all properties (name, indoor) and no allOf.

Analysis

The behaviour changed with ada02a095 (#3377, "honour JSpecify @Nullable on controller parameters"). GenericParameterService.resolveTypeAndTypeAnnotationsForParameter now also forwards the annotations of the parameter's AnnotatedType itself. @Valid (like @NotNull) also targets TYPE_USE, so for createCat the request body is resolved with the context annotations [RequestBody, Valid, Valid] instead of [RequestBody, Valid]. The type-use annotations are read from the implementation method, while the parameter annotations are merged with the interface's, so updateCat keeps the old key and createCat gets a new one.

Because the ModelConverterContext is shared for the whole document build (SpringDocAnnotationsUtils.MODEL_CONVERTER_CONTEXT_MAP) and AnnotatedType.equals compares the context annotations, this new key leads to the following sequence (operations are processed in reverse RequestMappingInfo order):

  1. PUT /cats: Cat is resolved flat.
  2. POST /pets: resolving Animal makes ModelResolver.resolveSubtypes redefine Cat as allOf schema in the shared context.
  3. POST /cats, request body: 3.1.1 hits the cache. 3.2.0 has a new key, so ModelResolver resolves Cat again and defineModel replaces the allOf schema with a flat one in the shared context.
  4. POST /cats, response: AnnotationsUtils.getSchema resolves Cat in a fresh context and components.addSchemas overwrites the component with a flat schema.
  5. GET /cats/count: SpringDocAnnotationsUtils.extractSchema merges all models of the shared context into the components and prefers schemas with allOf. In 3.1.1 this restores the allOf version of Cat; in 3.2.0 the shared context only holds the flat one.

Possible fix

Skip type annotations that are already present among the parameter annotations before merging them, as DelegatingMethodParameter.getTypeUseAnnotations already does with !declaredAnnotations.contains(annotation). That keeps the cache keys of 3.1.1 for declaration-and-type-use annotations like @Valid/@NotNull, while type-use-only annotations such as JSpecify's @Nullable are still forwarded.

The underlying fragility is older, though: any resolution of a subtype under a new cache key after its parent has been resolved replaces the allOf form with a flat schema in the shared context, and whether the final document is correct then depends on operation order.

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.