OpenApi generator inheritance

Ergodox accent without international deadkey

OpenApi generator inheritance

Sun 31 May 2020 by Thibault Duperron in OpenAPI Generator, SpringBoot, OAS3

We have to create a new API with inheritance in the model. To continue with the contract first way, we will see how to write it in OAS3.

The requirement

We will create an API that can (surprise) manage ponies. We will work with two kinds of ponies, pegasi and unicorn.

target uml

The solution

We must use allOf for inheritance:

api.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


---
components:
  schemas:
    Pony:
      type: "object"
      properties:
        name:
          type: "string"
    Pegasi:
      allOf:
        - $ref: "#/components/schemas/Pony"
        - type: "object"
          properties:
            wingsColors:
              type: "string"
              default: "RED"
    Unicorn:
      allOf:
        - $ref: "#/components/schemas/Pony"
        - type: "object"
          properties:
            cornSize:
              type: "integer"
              default: 10
---

With this, we will have Pegasi and Unicorn that extend Pony. But if we generate the controller, it will not work well because it can’t say when to build a Pegasi or a Unicorn.

To specify this we need to use a discriminator.

api.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


---
components:
  schemas:
    Pony:
      discriminator:
        propertyName: ponyType
      type: "object"
      properties:
        name:
          type: "string"
        ponyType:
          type: string

    Pegasi:
      allOf:
        - $ref: "#/components/schemas/Pony"
        - type: "object"
          properties:
            wingsColors:
              type: "string"
              default: "RED"
    Unicorn:
      allOf:
        - $ref: "#/components/schemas/Pony"
        - type: "object"
          properties:
            cornSize:
              type: "integer"
              default: 10
---

The discriminator is added to the model because it will be in. It must not be treated as a hidden property because it will mess clients.

If you want to fix it, it can be specified with mapping property.

api.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


---
components:
  schemas:
    Pony:
      discriminator:
        propertyName: ponyType
        mapping:
          pegasi: "#/components/schemas/Pegasi"
          unicorn: "#/components/schemas/Unicorn"
      type: "object"
      properties:
        name:
          type: "string"
        ponyType:
          type: string

    Pegasi:
      allOf:
        - $ref: "#/components/schemas/Pony"
        - type: "object"
          properties:
            wingsColors:
              type: "string"
              default: "RED"
    Unicorn:
      allOf:
        - $ref: "#/components/schemas/Pony"
        - type: "object"
          properties:
            cornSize:
              type: "integer"
              default: 10
---

OneOf?

Our first try was with oneOf, but it’s not for inheritance it’s a composition, it’s create an object that can be both a Pegasi and a Unicorn, but in a way that says Pegasi and Unicorn are two disjoint objects with nothing common.

Links

Demo project

OpenAPI Generator