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

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.

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.