"oneOf" from superclass schema is propagated to subclasses unexpectedly

[YoungHoney]

Hello ~ I have a question about oneOf propagation in a superclass–subclass relationship.

Version

• Java 17
• org.springframework.boot' version '3.5.4' // 'org.springframework.boot:spring-boot-starter-web'
• org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.9

My Code

//--- Cat.java
@JsonTypeName("cat")
@Schema(description = "it's a cat")
public class Cat extends Pet {
    private double cuteness;
}

//--- Dog.java
@JsonTypeName("dog")
@Schema(description = "it's a dog")
public class Dog extends Pet {
    private String barkSound;
}

//--- Pet.java 
@Schema(
    description = "it's super pet",
    discriminatorProperty = "petType",
    oneOf = { Cat.class, Dog.class },
    requiredProperties = {"petType"}
)
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "petType")
@JsonSubTypes({
    @JsonSubTypes.Type(value = Cat.class, name = "cat"),
    @JsonSubTypes.Type(value = Dog.class, name = "dog")
})
public abstract class Pet {
    private String name;
    private int age;
    private String petType;
}

//--- PetController.java
@GetMapping("/pets", produces = MediaType.APPLICATION_JSON_VALUE))
public List<Pet> getPets() { ... }

Result

When I open /swagger-ui.html and check the UI:

• Pet → oneOf(Cat, Dog) ✅ (correct for polymorphism)
• But in the schema UI, Cat and Dog also appear as oneOf siblings (misleading, because they are subclasses of Pet, not interchangeable with each other directly).

Problem

This may confuse API consumers, because it looks like Cat and Dog have a direct polymorphic relation between each other, when in fact they only share a parent class.

Question

I tried to find any similar issues or discussions about this behavior but couldn’t find one.
Is this:

1. A known/expected behavior?
2. A bug in springdoc-openapi?
3. Or something that is documented somewhere but I missed?

[Mattias-Sehlstedt]

Hi @YoungHoney,

This is an issue I am familiar with, it has been discussed here. It has to do with how swagger-core introspects. It both parses the @JsonSubTypes annotation but also the @Schema annotation, meaning that the generated OpenApi object tries to express two different ways of representing polymorphism.

There are several different solutions to this, with the main thing being that you need to not have both annotations on the same object.

[YoungHoney]

Thanks for the clarification!
I’ll make sure to check out the issue you mentioned.