Swashbuckle.webapi: No equivalent for PolymorphicType

[chris-peterson]

Thoughts on a migration path for PolymorphicType usages?

I currently use it for influencing both request and response documentation, e.g. payment methods:

c.PolymorphicType<PaymentMethod>(pc => pc
    .DiscriminateBy(p => p.Type)
    .SubType<CreditCard>()
    .SubType<Paypal>());

[domaindrivendev]

Swagger 2.0 describes types using a swagger-specific version of JSON Schema. However, it does not support the "oneOf" construct, which I believe is what you're looking for here. Here's the related issue:

https://github.com/swagger-api/swagger-spec/issues/57

As you can see, there is some debate around the rationale but theoretically, I (kind of) agree. If you decide that "PaymentMethod" is the right abstraction for an interface, then "any" PaymentMethod should work, not just a known subset. Otherwise, you have a less explicit interface and more ambiguity that can only be resolved through documentation.

If I were designing your "order processing" API today ;-), I would consider being more explicit. Either defining explicit resources like "/orders/with-credit-card", "/orders/with-paypal" etc. or by redefining the "PaymentMethod" format as follows:

{
    "type": "credit-card",
    "credit-card-details: {} // optional
    "paypal-details: {} //optional
}

Of course, I'm sure breaking the contract isn't an option for you especially if the current consumers have no problem with polymorphism. So, given the lack of support in Swagger, the only options I can think of are 1) describe the hierarchy through text comments on the base type or 2) flattening PaymentMethod server-side. Incidentally, the latter wouldn't break the contract in any way. But, instead of thinking of it as a polymorphic type, you would be forcing consumers to think of it as a data structure with optional fields dependent on the "type" value.