Discussion on @JsonTypeInfo @JsonSubTypes to implement different types of parameters

[linwumingshi]

Discussion from issues #375 , #614

Abstract Class

/**
 * Abstract class for Animals.
 * <pre>
 *     1. Added the @JsonTypeInfo annotation to specify how subclass type information should be handled.
 *      1.1 Configuration of use:
 *          1.1.1 Using `use = JsonTypeInfo.Id.CLASS` indicates that the subtype information should be used as a type identifier. For example, "type":"com.power.doc.model.json.type.info.Dog".
 *          1.1.2 Using `use = JsonTypeInfo.Id.NAME` indicates that the value of the property should be used as a type identifier. For example, "type":"dog".
 *          1.1.3 Using `use = JsonTypeInfo.Id.MINIMAL_CLASS` indicates that the value of the property should be used as a type identifier. For example, "type":".Dog".
 *      1.2 Configuration of property: specifies the distinguishing field.
 *     2. Added the @JsonSubTypes annotation to specify the subtypes.
 *      2.1 Added the @JsonSubTypes.Type annotation to specify the subtypes.
 * </pre>
 *
 * @author linwumingshi
 */
@Data
@JsonTypeInfo(
        use = JsonTypeInfo.Id.NAME,
        include = JsonTypeInfo.As.PROPERTY,
        property = "type"
)
@JsonSubTypes({
        @JsonSubTypes.Type(value = Dog.class, name = "dog"),
        @JsonSubTypes.Type(value = Cat.class, name = "cat"),
        @JsonSubTypes.Type(value = Bird.class, name = "bird")
})
public abstract class Animal {
    /**
     * The name of the animal.
     */
    private String name;

    public Animal() {
    }

    public Animal(String name) {
        this.name = name;
    }

}

Children Class

Bird

/**
 * animal bird
 *
 * @author linwumingshi
 */
@EqualsAndHashCode(callSuper = true)
@Data
public class Bird extends Animal {
    /**
     * wingSpan
     */
    private double wingSpan;
    /**
     * nickName
     */
    private String nickName;

    public Bird() {
        this.nickName = "bird";
    }

    public Bird(String name, double wingSpan) {
        super(name);
        this.nickName = "bird";
        this.wingSpan = wingSpan;
    }

}

Cat

/**
 * animal cat 🐱
 *
 * @author linwumingshi
 */
@EqualsAndHashCode(callSuper = true)
@Data
public class Cat extends Animal {
    /**
     * can climb
     */
    private boolean climb;

    /**
     * nickName
     */
    private String nickName;

    public Cat() {
        this.nickName = "mi mi \uD83D\uDC31";
    }

    public Cat(String name, boolean climb) {
        super(name);
        this.nickName = "mi mi \uD83D\uDC31";
        this.climb = climb;
    }
}

Dog

/**
 * animal dog 🐕
 *
 * @author linwumingshi
 */
@EqualsAndHashCode(callSuper = true)
@Data
public class Dog extends Animal {
    /**
     * can bark
     */
    private boolean bark;
    /**
     * nickName
     */
    private String nickName;

    public Dog() {
        this.nickName = "wang wang \uD83D\uDC15";
    }

    public Dog(String name, boolean bark) {
        super(name);
        this.nickName = "wang wang \uD83D\uDC15";
        this.bark = bark;
    }
}

Person (Class containing abstract class attributes)

@Data
public class Person {

    /**
     * pet
     */
    private Animal pet;

    /**
     * person name
     */
    private String name;
}

Example

@RequiredArgsConstructor
@RestController
@RequestMapping("/animals")
public class JsonTypeInfoAnimalController {


    /**
     * save an animal
     *
     * @param animal animal(Dog, Cat, Bird)
     * @return animal(Dog, Cat, Bird)
     */
    @PostMapping
    public Animal saveAnimal(@RequestBody Animal animal) {
        return animal;
    }

    /**
     * save a person with animal
     *
     * @param person person
     * @return person
     */
    @PostMapping("/person")
    public Person savePersonWithAnimal(@RequestBody Person person) {
        return person;
    }

Current Behavior

Body-parameters:

Parameter	Type	Required	Description	Since
name	string	false	name	-

Response-fields:

Field	Type	Description	Since
name	string	name	-

Body-parameters(with nested object):

Parameter	Type	Required	Description	Since
pet	object	false	pet	-
└─name	string	false	name	-
name	string	false	person name	-

Response-fields(with nested object):

Field	Type	Description	Since
pet	object	pet	-
└─name	string	name	-
name	string	person name	-

💡 Solution One

The ApiParam class add field oneOf

	/**
	 * oneOf
	 */
	private List<ApiParam> oneOf;

OpenApi Or Swagger document

oneOf, anyOf, allOf, not

MarkDown Or Html document

In the documentation for the abstract (parent) class API, include anchor links to the descriptions of its subclasses.

Body Parameters

Parameter	Type	Required	Description	Since
pet	object	false	Pet	-
└─ type	string	false	Type of the animal (Dog , Cat, Bird)	-
name	string	false	Person name	-

Dog

Parameter	Type	Required	Description	Since
name	string	false	Name of the dog	-
bark	boolean	false	Can bark	-
nickName	string	false	NickName	-

Cat

Parameter	Type	Required	Description	Since
name	string	false	Name of the cat	-
climb	boolean	false	Can climb	-
nickName	string	false	NickName	-

Bird

Parameter	Type	Required	Description	Since
name	string	false	Name of the bird	-
wingSpan	double	false	Wingspan	-
nickName	string	false	NickName	-