Правильное использование полиморфизма / наследования в Open API 3 - PullRequest
Новая
       7

Правильное использование полиморфизма / наследования в Open API 3

3 голосов
/ 22 января 2020

Я что-то упускаю при правильном использовании полиморфизма в Open API 3.

В в документе спецификации (3.0.2) , в примере используется oneOf, и, необязательно, Discriminator block: 

    MyResponseType:  
     oneOf:
      - $ref: '#/components/schemas/Cat'
      - $ref: '#/components/schemas/Dog'
      - $ref: '#/components/schemas/Lizard'  
     discriminator:
        propertyName: petType

В этом сценарии единственное ограничение, которому Cat, Dog и Lizard должны удовлетворять, - это обязательное поле petType и предварительно определенное значение. Позже можно прочитать:

Чтобы избежать избыточности, дискриминатор МОЖЕТ быть добавлен к определению родительской схемы, и все схемы, включающие родительскую схему в конструкции allOf, могут использоваться в качестве альтернативной схемы.

Я нахожу это хорошим, поскольку он предлагает правильное использование естественного наследования 3 сущностей: 

components:
  schemas:
    Pet:
      type: object
      required:
      - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog
    Cat:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Cat`
        properties:
          name:
            type: string
etc

Кстати, spe c немного двусмысленно with

Объект дискриминатора допустим только при использовании одного из составных ключевых слов oneOf, anyOf, allOf

Pet не содержит ни одного из этих ключевых слов!

Однако во втором примере не показаны последствия для блока MyResponseType.

  1. Остаётся ли оно прежним? Если так, что должно быть сгенерировано, скажем, в Java? MyResponseType и Pet классы? Как должен выглядеть класс MyResponseType?
  2. Следует ли удалить из файла MyResponseType и использовать вместо него Pet? Если это так, редактор сваггеров больше не способен отслеживать подтипы ...
  3. Затем, следует ли добавить oneOf к схеме Pet, чтобы редактор сваггеров мог отображать подтипы? Я пробовал, это работает, и валидаторы говорят, что это Open API 3-совместимый, , но предупреждают, что цикл мешает. Мне кажется, что это было бы формально неправильно: тело http с Cat (petType Cat) со всеми свойствами Cat и Dog могло бы быть проверено из-за oneOf Cat / Dog / Lizard, унаследованного от Pet. Правильно ли я истолковал это так?
...