How do I specify a payload that allows different sub types?

[Jeff Haynes]

I am trying to design an endpoint of our API and the payload is an object which (in Java) is represented by a base class and several sub classes.

definitions:
  AnimalType:
    type: string
    enum: &animal_type_values
    - dog
    - cat
    - pig
    - horse

  EntityType:
    description: An enumeration of the supported entity types
    type: string
    enum:
    - Animal
    - Crop
    - Person
    - Building

  Entity:
    discriminator: entity_type
    required:
      - entity_type
      - id
    properties:
      id:
        type: integer
        format: int64
        readOnly: true
        description: The internal entity id for this entity representation
        example: 1438752
      entity_type:
        $ref: '#/definitions/EntityType'

  AnimalPayload:
    discriminator: animal_type
    allOf:
      - $ref: '#/definitions/Dog'
      - $ref: '#/definitions/Cat'
      - $ref: '#/definitions/Pig'
      - $ref: '#/definitions/Horse'

  Animal:
    discriminator: animal_type
    allOf:
      - $ref: '#/definitions/Entity'
      - type: object
        required:
          - animal_type
        properties:
          animal_type:
            $ref: '#/definitions/AnimalType'
          name:
            type: string
            readOnly: true    
          birth_date:
            type: string
            format: date
          gender:
            type: string
            enum:
            - male
            - female

  Dog:
    allOf:
      - $ref: '#/definitions/Animal'
      - type: object
        properties:
          breed:
            type: string
           
  Cat:
    allOf:
      - $ref: '#/definitions/Animal'
      - type: object
        properties:
          num_lives:
            type: integer
            format: int32

  Pig:
    allOf:
      - $ref: '#/definitions/Animal'
      - type: object
        properties:
          color:
            type: string

  Horse:
    allOf:
      - $ref: '#/definitions/Animal'
      - type: object
        properties:
          breed:
            type: string
            tamed:
              type: boolean
paths:
  /animals:

    post:
      parameters:
        animal:
          name: animal
          in: body
          schema:
            - $ref: '#/parameters/Dog'
            - $ref: '#/parameters/Cat'
            - $ref: '#/parameters/Pig'
            - $ref: '#/parameters/Horse'

I know this is not valid, but how do I get this to work in some form? I would like to simply use a Dog, Cat, Pig, or Horse object as the payload.

The only way I can think of is to create the AnimalPayload object. That is messy and confusing. Am I missing something? Can I model this differently to make this work more intuitively?

[Ron Ratovsky]

You just set the body parameter to be Animal. The rest inherit from it, and are valid as input.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Jeff Haynes]

Does that show all the fields for each type through swagger-ui and swagger-editor?

And does that allow validation of the sub types?

Thanks

You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/Jkz8lvE4s5A/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Ron Ratovsky]

Currently, neither tool will show those fields. And since neither of them performs validation on responses, sub types are irrelevant.

[Jeff Haynes]

Thanks for the response.

You spoke about responses. What about as part of a payload?

Thanks

[Ron Ratovsky]

Should have been clearer, sorry.

 

For requests, the validation is limited to primitives, mostly.

I believe that if you enable the JSON Schema Form editor (in swagger-ui), you will get some basic field-level validation for the payload fields, but it still doesn’t support the inheritance model.

[Jeff Haynes]

Thanks

[Jeff Haynes]

How do I enable the JSON Schema Form editor?

[Ron Ratovsky]

Take a look at https://github.com/swagger-api/swagger-ui#parameters.