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

Chiusa
  • Qualcosa non va?
#3,393 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 9 giorni

@jochenberger ci sta già lavorando.

Dal 27/10/2026.

  • #3394 di @jochenberger — aperta

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
30/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
java, openapi, spring, spring-boot
Ambito
api, documentation

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Java
Stelle
3.7k
Fork
605
Merge medio
9g 11h
PR unite (30g)
14

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di springdoc/springdoc-openapi

Tutte le issue di springdoc/springdoc-openapi

Issue simili

Altre issue su Java

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.