Swashbuckle.webapi: Polymorphism Support

[johnpmcclung]

Swagger Spec - Polymorphism
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#models-with-polymorphism-support

Are there plans to support this at the configuration level?

Or is there currently support for:

public class AnimalController : ApiController
{
   public IHttpActionResult Post(Animal animal)
   {
      return Ok();
   }
}

How can I document that they can post a Dog, Cat, or Duck(any subtype)? I don't necessarily need the "allOf" property from the spec but I would like to add the subtypes to the definitions.

Thank you for any help in advance.

[domaindrivendev]

Really what you need is support for "oneOf", so you're animal schema could be described as follows:

{
    "oneOf": [
        { "$ref": "Dog" },
        { "$ref": "Cat" },
        { "$ref": "Duck" }
    ]
}

However, this is NOT supported in Swagger - https://github.com/swagger-api/swagger-ui/issues/1056

They have their practical reasons. I, on the other hand, "partly" agree with the call from a design perspective. Why should a consumer need to worry about which sub-classes are valid when the operation clearly states that "any" Animal is valid. If there is something in the semantics of the operation concerned about the specifics of the animal, then maybe this should be expressed through a separate operation (see the Liskov Substitution Principle for more on this).

[Route("/api/dogs")]
public IHttpActionResult Post(Dog dog)

Another way of looking at it ... in C#, you can't instantiate an abstract class, you have to call the specific constructor of a subclass. It's the exact same principle, at the code level it's the constructor, at a REST API level - it's the collection URI you're posting to.

So, after all that ranting :), I can't think of a good way to answer your question without rethinking your API design. Sorry if this isn't very helpful.

[GaTechThomas]

We are currently using Swashbuckle to generate the json document at http://localhost:54321/swagger/docs/v1 to see diffs in our interface as we develop it. We just keep the file in source control and compare diffs. It has been very helpful in seeing precise differences that we have introduced with code changes.

We have a WebApi REST endpoint that consumes something like the following pseudocode:

class HolderClass
{
int TopLevelField1;
string TopLevelField2;
decimal TopLevelFieldN;
PolymorphicBase poly;
}

class PolymorphicBase
{
int Type;
}

class Child1 : PolymorphicBase
{
string Child1Field1;
}

class Child2 : PolymorphicBase
{
string Child2Field1;
int Child2Field2;
}

The way that Swashbuckle currently generates a Swagger spec file is that it only shows info about HolderClass and about PolymorphicBase. Nowhere does it acknowledge the child classes.

Is there anything we can do to make Swashbuckle output the child classes in the json spec file? We don't need anything to work beyond that. We don't even need to know that they inherit from the parent (though it would be nice to have).

Can we accomplish this without a lot of work and without forking the Swashbuckle repository?

[assafi]

According to this discussion in the Swagger 2.0 specification the suggested workaround is using the polymorphism specification. Are there any plans to support this in V5.0+?