Polymorphism in models

[MatMoore]

This is a follow up to #7 which was a broader question about resource pages. Since then I've created a few branches to experiment with different schemas.

The open api spec talks about polymorphic model definitions here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#composition-and-inheritance-polymorphism

While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, Swagger adds the support of the discriminator field. When used, the discriminator will be the name of the property used to decide which schema definition is used to validate the structure of the model. As such, the discriminator field MUST be a required field. The value of the chosen property has to be the friendly name given to the model under the definitions property. As such, inline schema definitions, which do not have a given id, cannot be used in polymorphism.

I noticed we were already using allOf in the examples:
Pet is a supertype of Cat and Dog, and has a petType discriminator. Pet wasn't referred to directly in any responses though.

What I'd like to do is declare that a response contains pets, and somehow be able to see what the Cat/Dog fields are from the Pet resource page.

I added an example of what I mean in this commit: https://github.com/MatMoore/swaggerly/commit/b000bb42d64ff79c6bea11db3aecc975ae10fd90

My questions are:

• Do I understand the spec correctly when it comes to polymorphic responses?
• Is it something you'd want to support in swaggerly?

[zxchris]

It appears that go-openAPI does not expose the constituent parts of a composed resource, so we have been struggling to get this documentation generated.

Will leave this issue open for the time being, in case some trick presents itself!

[zxchris]

May have to open an issue with go-openAPI for this.