Am I using discriminator right?

[jan-matejka]

Description

The OpenAPI v2.0 spec defines discriminator and shows how to define objects with it but not how it can be actually used.

I have code like this

Swagger declaration file content or url

swagger: '2.0'

info:
  title: "sscce"
  version: '1.0'
  description: sscce

definitions:

  Animal:
    type: object
    discriminator: animal_type
    properties:
      animal_type:
        type: string

  Bear:
    allOf:
      - $ref: "#/definitions/Pet"
      - type: object
        required:
          - color
        properties:
          color:
            type: string
            enum:
              - white
              - brown

  Cat:
    allOf:
    - $ref: "#/definitions/Pet"
    - type: object
      required:
        - likes_water
      properties:
        likes_water:
          type: boolean


paths:
  /foo:
    post:
      parameters:
        - name: animal
          in: body
          schema: {$ref: "#/definitions/Animal"}
      responses:
        "200":
          description: foo
          type: string

and what I am trying to do is essentialy define an algebraic sum type Animal = Cat | Bear meaning a parameter defined as of type Animal must contain either a type of Cat or a type of Bear.

But when I do this, the parameter animal is defined just as plain Animal and the types Cat and Bear are not even shown to be present in the spec.

First thing I could do is to forget about the subtypes and just put the attributes into Animal but then it doesn't make much sense as Bears universally do not have a problem with water (if I am wrong here, please bear (see what I did there) with me; I'm doing my best to come up with sane analogy) and then cats can't really be universally assigned a color attribute as some are rather patterned. Anyhow, I'm screwed.

Another thing I could do is to defined separate POST paths like

/animal/bear:
  post:
    -name: bear
     schema: {$ref: "#/definitions/Bear"}

and similar for cat ... and while that would work and generally I'd be ok with it but I need these as part of another algebraic product type (complex type, user defined type, whatever ...) where I could use a similar approach but in the real case my Animal types have a natural primary key so I can lump them together within the containing type into a single POST request, cutting down latencies on saved roundtrip.

I guess this is basicly
OAI/OpenAPI-Specification#57
chop-dbhi/serrano#302
and I am aware of the oneOf feature in OpenAPI v3.0 but

1. swagger-codegen doesn't seem to support v 3.0 and I'm not even sure if v3.0 is finalized
2. is there something I can do with this in v2.0 and
3. am I misunderstading discriminator?

Swagger-codegen version

current master; HEAD = 1c160df

Command line used for generation

JAR=".../swagger-codegen.git/modules/swagger-codegen-cli/target/swagger-codegen-cli.jar"
java -jar "${JAR}" generate -i ~/sscce.yaml -l html2 -o foo

[silkentrance]

Maybe this helps: https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/