Polymorphism is incorrectly lost depending on available paths

[slw546]

Consider the below API:

public class MyApi {
        @GET
	@Path("/random")
	@Produces(MediaType.APPLICATION_JSON)
	public Pet random() {
		Random rand = new Random();

		if (rand.nextBoolean())
			return new Cat(rand.nextBoolean());
		else
			return new Dog(rand.nextBoolean());
	}
}


@Schema(
	type = "object",
	title = "Pet",
	subTypes = { Cat.class, Dog.class },
	discriminatorMapping = {
			@DiscriminatorMapping( value = "CAT", schema = Cat.class ),
			@DiscriminatorMapping( value = "DOG", schema = Dog.class )
	},
	discriminatorProperty = "petTypeAsString"
)
public class Pet {

	public enum PetType {
		CAT,
		DOG;
	}

	@Schema(required = true)
	public PetType petType;

	@Schema(required = true)
	public String petTypeAsString;

	public Pet() {}

	public Pet(PetType petType) {
		this.petType = petType;
		this.petTypeAsString = petType.name();
	}
}

public class Cat extends Pet{
        public boolean hunts;

        public Cat() {
            super(Pet.PetType.CAT);
        }

        public Cat(boolean hunts) {
            this();
            this.hunts = hunts;
        }
}

public class Dog extends Pet{
        public boolean barks;

        public Dog() {
            super(Pet.PetType.DOG);
        }

        public Dog(boolean barks) {
            this();
            this.barks = barks;
        }

 }

The above example properly generates Cat and Dog with allOf: - $ref: '#/components/schemas/Pet', so I can use a client side generator to correctly reproduce the type heirarchy.

If I add a new method like this:

@PUT
@Path("/putDog")
@Produces(MediaType.APPLICATION_JSON)
public void putDog(Dog d) {}

Now, my spec generates with Dog missing the allOf:

   Dog:
   "type": "object"
   "properties": {
       "barks": {
          "type" : boolean"
       },
      "petType": {
           "type": "string",
           enum: [ "CAT", "DOG" ]
       },
      "petTypeAsString": {
           "type": "string"
       }
   },
   "required": ["petType", "petTypeAsString"]

This has the correct properties, but since the allOf is lost, I can no longer generate this as a subclass of Pet correctly.

It turns out in fact you can force the allOf to generate again by declaring a method with the abstract type as the parameter e.g.

@PUT
@Path("/putPet")
@Produces(MediaType.APPLICATION_JSON)
public void putPet(Pet p) {
    if (p instanceOf Dog) putDog((Dog) p)
    else ....
}

Given that the /random method can already return Pet, this seems to be a bug. I shouldn't need to provide putPet just to force it to respect the polymorphism of Pet if I want two separate putCat and putDog methods. Stepping through in the debugger, I can see that when we process /random there is a ComposedSchema generated, but this is later replaced when we process putDog - the code should be reusing the generated Schema for Dog from /random, not creating an incorrect one that treats it as a concrete class with no super types.

This also bites if you have a class like

public class ManyPets {
    public final Array[Pet] thePets;
    public ManyPets(Array[Pet] pets) {
     this.thePets = pets;
   }
}

and methods like

@PUT
@Path("/putCat")
@Produces(MediaType.APPLICATION_JSON)
public void putDog(Cat c) {}

@PUT
@Path("/putDog")
@Produces(MediaType.APPLICATION_JSON)
public void putDog(Dog d) {}

@PUT
@Path("/putMultiple")
@Produces(MediaType.APPLICATION_JSON)
public void putMultiple(ManyPets pets) {}

The putMultiple path will correctly generate ComposedSchemas for Cat and Dog with allOfs present, but the two other puts will replace those schemas and strip the allOf from the final spec.

Code generated via an openApi client generator will now be unable to see that Cat and Dog are suitable subtypes to provide to ManyPets.

This happens with or without adding the property "springdoc.model-converters.polymorphic-converter.enabled=false" which I have seen on some other related issues.

I'm reasonably sure this worked on springdoc-openapi 1.4.0 and could be convinced to generate correctly with no workarounds, and broke in 1.6.6. That said, I can't retry with 1.4.0 as it had log4j vulnerabilities

[bnasslahsen]

@slw546,

See the answer here #1572

[slw546]

@bnasslahsen , I am using the example and the suggested fix from that issue i.e. providing "springdoc.model-converters.polymorphic-converter.enabled=false". That fixes #1572 by making /random generate as expected, but it does not fix my issue.

The problem here is that the component schema for Cat and Dog do not generate an allOf #ref to Pet if there is a method that refers to them directly, even if other methods refer to Pet polymorphically.

 "schemas" : {
      "Cat" : {
        "type" : "object",
        "properties" : {
          "hunts" : {
            "type" : "boolean"
          },
          "petType" : {
            "type" : "string",
            "enum" : [ "CAT", "DOG" ]
          },
          "petTypeAsString" : {
            "type" : "string"
          }
        },
        "required" : [ "petType", "petTypeAsString" ]
      },
      "Dog" : {
        "type" : "object",
        "properties" : {
          "barks" : {
            "type" : "boolean"
          },
          "petType" : {
            "type" : "string",
            "enum" : [ "CAT", "DOG" ]
          },
          "petTypeAsString" : {
            "type" : "string"
          }
        },
        "required" : [ "petType", "petTypeAsString" ]
      }

so generated code does not produce subtypes:

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen", date = "2022-03-30T04:37:34.089-04:00[US/Eastern]")
public class Cat { ... }

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen", date = "2022-03-30T04:37:34.089-04:00[US/Eastern]")
public class Dog {

I would expect both of these to extend Pet (which they indeed do if the allOf is preserved by one of the workarounds discussed)

The expected output is:

 "schemas" : {
      "Cat" : {
        "type" : "object",
        "allOf" : [ {
          "$ref" : "#/components/schemas/Pet"
        } ],
        "properties" : {
          "hunts" : {
            "type" : "boolean"
          }
        },
        "required" : [ "petType", "petTypeAsString" ]
      },
      "Dog" : {
        "type" : "object",
        "allOf" : [ {
          "$ref" : "#/components/schemas/Pet"
        } ],
        "properties" : {
          "barks" : {
            "type" : "boolean"
          }
        },
        "required" : [ "petType", "petTypeAsString" ]
      },

which generates e.g.

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen", date = "2022-03-30T04:44:12.631-04:00[US/Eastern]")
public class Dog extends Pet { .. }

@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen", date = "2022-03-30T04:44:12.631-04:00[US/Eastern]")
public class Cat extends Pet { ... }

[slw546]

@bnasslahsen Adding

@Schema(allOf = Pet.class)

to both of my concrete classes does fix this, but it's not clear to me why this hint annotation is required only in the case where I have methods that refer to the concrete classes, given we can correctly infer this if I omit those two methods.

[slw546]

@bnasslahsen can you please reopen this issue? #1572 fixes allOf in the content of a response i.e.

"responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Pet"
                }
              }
            },
            "description" : "OK"
          },

My issue is that allOf is not correctly produced in the schema of components, which means generators cannot properly produce the model. The suggested fix in #1572 only addresses content of responses, and does not fix my issue. I am already setting that property, as mentioned above.

[bnasslahsen]

@slw546,

The issue could be reopened, if it's confirmed on the springdoc-openapi side.

You could use ModelConverters.getInstance().resolveAsResolvedSchema(new AnnotatedType(Cat.class)); to inspect the content.

You have sample code here #1094

If you see you are facing the same bug, you should raise an issue to the swagger-core project instead.

[slw546]

@bnasslahsen,

I tracked down the issue - since you inspect methods in reverse alphabetical order, and never replace a schema once it's added to the components, you have an ordering problem where a non-composed schema will not be correctly replaced if you decide that it should be composed due to a later method. Please see my proposed fix

edit: this is also why in the above example, adding something like putPet fixed it - it was coincidentally the first method reverse-alphabetically, so it inserted ComposedSchemas before anything else could add incorrect ones. Likewise, adding an explicit allOf hint in a schema annotation forces them to generate correctly regardless of order, but it's preferable if the framework can correctly introspect polymorphism itself as then we're impervious to user mistakes