[Go] Support polymorphic substitution ("subclasses")

Description

This is a suggestion to generate go interfaces in the go code, or some other mechanism to support sub-classes.

The OAS spec supports polymorphism and inheritance. One area that seems to be problematic in the generated go code is when a schema refers to a type that has multiple sub-types, and the actual sub-type is determined at run-time by the api service. The go code is generated with a pointer to a struct (not an interface), which means there is no possibility of dynamically determining the proper go struct based on the discriminator value.

For example, suppose an OAS API specifies a path that returns a heterogenous list of animals. The returned list may include dogs, cats, and any "subclass" of animal. The api service may return a list of animals, and each object in the array may have a different discriminator value (e.g. Dog, Cat). This scenario can also apply to a component: for example, the Animal type may have a property which specifies a list of visited places, and each "Place" may have sub-types. A place could be a city, country or other types of places.

With the OpenAPITools generated code, the go client will unmarshal the list of Animals into the "Animal" go struct, and it will lose all the properties that were specified in the sub-types (such as Dog and Cat).

To address this problem, we have created a custom go implementation, and we generate a golang interface for each specified type in a OAS schema. The go type of the generated property is the (generated) go interface, not a pointer to a go struct. This makes it a bit harder to unmarshal because the default go unmarshaler does not know which type to instantiate. But this can be handled with a custom, generated JSON unmarhshaler; the unmarshaler reads the value of the discriminator property to determine the actual type, then it instantiates the proper go struct (e.g. Dog or Cat).

When there is a small and fixed number of sub-types, one could argue "oneOf" should be used to provide an explicit list of all sub-types. Besides the fact that currently the generators do not handle oneOf, it would ugly when the number of sub-types grows to a large value.

Is there a strong reason to generate pointers to go structs as opposed to go interfaces? Are there other approaches that work for polymorphic substitution? It seems the OAS spec is not very clear on that topic.

openapi-generator version

4.2.1

OpenAPI declaration file content or url

paths:
 /Animals:
    get:
      responses:
        '200':
          description: a heterogeneous (dogs, cats...) list of animals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Animals'

components:
  schemas:
    Resource:
      discriminator:
        propertyName: objectType
      properties:
        objectType:
          type: string
    Place:
      allOf:
        - $ref: '#/components/schemas/Resource'
        - type: object
          properties:
            name:
              type: string
    City:
      type: object
      allOf:
        - $ref: '#/components/schemas/Place'
        - type: object
          properties:
            zipCode:
              type: string
    Country:
      type: object
      allOf:
        - $ref: '#/components/schemas/Place'
        - type: object
          properties:
            countryCode:
              type: string
    Animal:
      type: object
      allOf:
        - $ref: '#/components/schemas/Resource'
        - type: object
          properties:
            name:
              type: string
            visitedPlaces:
              type: array
              description: the list of places (cities and countries) that this animal has visited.
              items:
                $ref: '#/components/schemas/Place'
   Dog:
      type: object
      allOf:
        - $ref: '#/components/schemas/Animal'
        - type: object
          properties:
            breed:
              type: string
    Cat:
      type: object
      allOf:
        - $ref: '#/components/schemas/Animal'
        - type: object
          properties:
            color:
              type: string
    Animals:
      type: array
      items:
        $ref: '#/components/schemas/Animal'

Command line used for generation

Steps to reproduce

Related issues/PRs

https://github.com/OAI/OpenAPI-Specification/issues/403

Suggest a fix

Start by examining the Go generator's current handling of discriminator, allOf, and generated pointers using the supplied Animal, Dog, Cat, Place, City, and Country schema. Compare possible interface and custom-unmarshaling approaches, then validate the chosen design against heterogeneous arrays and nested subtype properties. Done should mean subtype-specific fields are preserved during unmarshaling.