How to describe polymorphic endpoint

[raderio]

We use Spring+Jackson(Java). And in our API we can send different object to same endpoint.
For example

  @JsonTypeInfo(
      use = JsonTypeInfo.Id.NAME, 
      include = As.PROPERTY, 
      property = "type")
    @JsonSubTypes({
        @JsonSubTypes.Type(value = Dog.class, name = "dog"),
        @JsonSubTypes.Type(value = Cat.class, name = "cat")
    })
    public static class Animal {
    }
 
    @JsonTypeName("dog")
    public static class Dog extends Animal {
        public double barkVolume;
    }
 
    @JsonTypeName("cat")
    public static class Cat extends Animal {
        boolean likesCream;
        public int lives;
    }

@Controller
public class MyController {

    //REST service
    @RequestMapping( value = "test")
    public  @ResponseBody String save(@RequestBody  Animal animal){
        System.out.println(animal.getClass());
        return success;
    }
}

Sending to /test

{
    "type": "dog",
    "barkVolume": 23.3
}

will show Dog.class

Sending to /test

{
    "type": "cat",
    "likesCream": true,
    "lives": 42
}

will show Cat.class

How to describe polymorphic endpoint in Swagger?

[Martin-Luft]

One problem is, that Swagger does not evaluate the @JsonTypeInfo annotation like mentioned here: #280 (comment) The type property is not a bean property and therefore Swagger does not recognize it :(

[mudit-sethi]

@frantuma Thanks for the fix. We really wanted this to be fixed. How can I try and test this fix? We are using swagger jaxrs2 plugin 2.0.8 at the moment.

[frantuma]

This is available in latest 2.0.9-SNAPSHOT, just reference this version (in case enabling snapshot repos in your pom)

[mudit-sethi]

@frantuma I got a chance to try your fix with the following:
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type") @JsonSubTypes({ @JsonSubTypes.Type(name = "DOG", value = DogDto.class), @JsonSubTypes.Type(name = "CAT", value = CatDto.class)})

the swagger doc shows me the 'type' field but not include the sub types in it as part of the generated doc

[frantuma]

your scenario seems to be working on e.g. in this test

can you share more details about the annotated resources and classes, the swagger configuration, and the resolved spec?

[mudit-sethi]

I have @Schema(type="object", discriminatorProperty = "type", required = true, oneOf = {Dog.class, Cat.class}) on the Animal class. I think it might be an issue with swagger-ui example not showing it correctly, when I look at the schema in UI then seems to be showing fine

[frantuma]

If i get it right, it might be an issue with swagger-ui? if this is the case, please open an issue there (providing the spec causing the issue)

[SabhtarshaMojo]

Hit a NPE when my model had some required fields but did not have the discriminatorProperty as part of the class definition.
Could fix it by changing the code here:

swagger-core/modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/ModelResolver.java

Line 1643 in 6c702f1

if (modelToUpdate.getRequired() == null || !model.getRequired().contains(typeInfoProp)) {

Changed the condition to following and it fixed it,
if (modelToUpdate.getRequired() == null || !modelToUpdate.getRequired().contains(typeInfoProp)) {

[frantuma]

thanks @SabhtarshaMojo , it was indeed a bug, fixed in #3293