"дискриминатор" в полиморфизме, OpenAPI 2.0 (Swagger 2.0)

Ссылка OpenAPI 2.0, объект схемы или Swagger 2.0, объект схемы и определение поля discriminator как:

Добавляет поддержку полиморфизма. Дискриминатор - это имя свойства схемы, которое используется для различения другой схемы, наследующей эту схему. Используемое имя свойства ДОЛЖНО быть определено в этой схеме, и оно ДОЛЖНО находиться в списке свойств required. При использовании значение ДОЛЖНО быть именем этой схемы или любой схемы, которая наследует его.

Мои путаницы/вопросы:

  • Мне неоднозначно, какую роль он играет в наследовании или полиморфизме. Может кто-нибудь объяснить discriminator рабочим примером, показывающим, что он делает, и что, если мы его не используем? Любые ошибки, предупреждения или любые инструменты, которые зависят от него для некоторых операций?
  • В этом случае swagger-editor не поддерживает discriminator, и это поле используется в некоторых других инструментах?

Что я пробовал до сих пор:

  • Я попытался использовать swagger-editor и пример из той же документации (также упоминавшейся ниже), чтобы играть с этим свойством посмотрим, смогу ли я увидеть какое-либо его особое поведение. Я изменил свойство, удалил его и расширил модель Dog на один уровень глубже и попробовал то же самое в новой подмодее, но я не видел никаких изменений в предварительном просмотре чванство-редактор.
  • Я пробовал искать в Интернете и специально вопросы, связанные с stackoverflow, но не нашел никакой соответствующей информации.

Пример кода, который я использовал для экспериментов:

definitions:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          default: lazy
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - huntingSkill
  Dog:
    description: A representation of a dog
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
      - packSize

Ответы

Ответ 1

В соответствии с этой группой goggle, discriminator используется поверх свойства allOf и определяется в супер-типе для полиморфизма. Если discriminator не используется, ключевое слово allOf описывает, что модель содержит свойства других моделей для композиции.

Как и в вашем примере кода, Pet является супер-типом с свойством petType, идентифицированным как discriminator и Cat, является подтипом Pet. Ниже приведен пример json объекта Cat:

{
  "petType": "Cat",
  "name": "‎Kitty"
}

Использование discriminator предназначено для указания свойства, используемого для идентификации типа объекта. Предполагается, что есть инструменты, которые могут правильно поддерживать объекты определения с использованием discriminator, можно определить тип путем сканирования свойства. Например, идентифицируйте объект как Cat в соответствии с petType.

Однако поле discriminator не определено в текущей спецификации версии или образцах (см. issue # 403). Насколько я знаю, в настоящее время инструментарий, предоставляемый Swagger, не поддерживает его в настоящий момент.

discriminator может использоваться, если модель имеет свойство, используемое для определения типа. В этом случае он естественно подходит, и его можно использовать в качестве индикатора для других разработчиков, понимающих взаимосвязь полиморфизма. Если сторонние инструменты вроде ReDoc, которые поддерживают discriminator (см. petType в этом gif и пример), вы можете найти это полезным.

Ответ 2

Функциональность дискриминатора была значительно улучшена в OpenApi 3. Теперь вы предоставляете объект дискриминатора, который содержит имя свойства дискриминатора, а также сопоставление значений этого свойства с именами схем.

(Я понимаю, что вы спросили об OpenApi 2, но это настолько улучшилось в 3, что, надеюсь, вы можете использовать его).

Смотрите: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject для фактической спецификации