Swagger 2.x如何通过@Schema实现多态SubTypes与Discriminator？替代1.5.x@ApiModel

Great question! When upgrading swagger-core from 1.5.x to 2.x (built for OpenAPI 3.0), swapping @ApiModel for @Schema requires a small but specific setup to replicate the polymorphism you had with @JsonSubTypes. Here's a step-by-step breakdown, plus useful resources beyond the official docs:

Core Setup for Polymorphism #

Swagger-core 2.x leans heavily on Jackson's type annotations for polymorphism, so you'll keep using @JsonTypeInfo and @JsonSubTypes alongside OpenAPI 3's @Schema annotations. Here's how to wire it up:

1. Parent Class Configuration #

On your base abstract class, combine Jackson's type info with @Schema to define all possible subclasses via the oneOf attribute. This tells OpenAPI that responses/requests using this type can be any of the listed subclasses:

import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
import io.swagger.v3.oas.annotations.media.Schema;

@JsonTypeInfo(
    use = JsonTypeInfo.Id.NAME,
    include = JsonTypeInfo.As.PROPERTY,
    property = "type" // This is the discriminator field that identifies the subclass
)
@JsonSubTypes({
    @JsonSubTypes.Type(value = Dog.class, name = "dog"),
    @JsonSubTypes.Type(value = Cat.class, name = "cat")
})
@Schema(
    oneOf = {Dog.class, Cat.class},
    discriminatorProperty = "type", // Explicitly map the Jackson discriminator field to OpenAPI
    discriminatorMapping = {
        @Schema.DiscriminatorMapping(value = "dog", schema = Dog.class),
        @Schema.DiscriminatorMapping(value = "cat", schema = Cat.class)
    }
)
public abstract class Animal {
    private String name;

    // Getters and setters
}

Note: The discriminatorProperty and discriminatorMapping are optional if you want swagger to auto-detect from Jackson's annotations, but explicit configuration makes your OpenAPI docs clearer.

2. Subclass Configuration #

For each subclass, use @Schema to set a name (matching the name value in @JsonSubTypes.Type) and description:

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(name = "dog", description = "A domestic canine with a breed attribute")
public class Dog extends Animal {
    private String breed;

    // Getters and setters
}

@Schema(name = "cat", description = "A domestic feline that may like catnip")
public class Cat extends Animal {
    private boolean likesCatsnip;

    // Getters and setters
}

Useful Resources Beyond Official Docs #

If you want more practical examples or troubleshooting tips, these are great places to look:

• swagger-core GitHub Examples: Check the project's examples module for runnable projects (like JAX-RS or Spring Boot integrations) that demonstrate OpenAPI 3 polymorphism. You can see how other developers have wired up similar setups in real-world code.
• GitHub Issue Tracker: Search for keywords like oneOf, polymorphism, or JsonSubTypes in the swagger-core repo. Many developers have posted specific edge cases and fixes—you might find a solution to a nuance the official docs don't cover.
• Developer Blog Posts: Look for Java-focused blogs (like Medium or DZone) where engineers have shared their swagger-core 2.x upgrade journeys. These posts often include step-by-step polymorphism migration guides with concrete examples.

内容的提问来源于stack exchange，提问作者vinodpthmn