"discriminateur" dans le polymorphisme, OpenAPI 2.0 (Swagger 2.0)

Question

référencement OpenAPI 2.0, Schema Object ou Swagger 2.0, Schema Object, et la définition du champ discriminator que:

ajoute le support pour le polymorphisme. Le discriminant est le nom de la propriété de schéma utilisé pour différencier les autres schémas qui héritent de ce schéma. Le nom de propriété utilisé DOIT être défini sur ce schéma et DOIT être dans la liste de propriétés required. Lorsqu'il est utilisé, la valeur DOIT être le nom de ce schéma ou de tout schéma qui en hérite.

Mes questions:/confusions

• Il est ambigu pour moi, quel rôle il joue exactement dans l'héritage ou polymorphisme. Pourrait-on expliquer s'il vous plaît discriminator avec un exemple de travail montrant ce qu'il fait exactement et si nous ne l'utilisons pas? Des erreurs, des avertissements ou des outils qui en dépendent pour certaines opérations?
• Est-il vrai que swagger-editor ne prend pas en charge discriminator et que ce champ est utilisé dans d'autres outils?

Ce que j'ai essayé jusqu'à présent:

• J'ai essayé d'utiliser swagger-editor et l'exemple de la même documentation (également mentionné ci-dessous), de jouer avec cette propriété pour voir si je peut voir l'un de ses comportements spéciaux. J'ai changé la propriété, l'ai enlevée et ai étendu le modèle Dog à un niveau plus profond et ai essayé la même chose sur le nouveau sous-modèle, mais je n'ai vu aucun changement dans l'aperçu de swagger-editor.
• J'ai essayé de chercher en ligne, et en particulier des questions de stackoverflow, mais je n'ai trouvé aucune information pertinente.

L'exemple de code que je faisais des expériences:

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 

Answer 1

Selon cette goggle group, discriminator est utilisé au-dessus de la propriété allOf et il est défini dans le type super pour le polymorphisme. Si discriminator n'est pas utilisé, le mot clé allOf décrit qu'un modèle contient les propriétés d'autres modèles pour la composition.

comme dans votre exemple de code, Pet est un type super avec propriété de petType identifié comme étant le discriminator et Cat est un sous type de Pet. Voici un exemple JSON d'un objet Cat:

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

L'utilisation de discriminator entend indiquer la propriété utilisée pour identifier le type d'un objet. Suppose qu'il existe des outils pouvant prendre en charge correctement les objets de définition avec l'utilisation de discriminator, il est possible de déterminer le type en analysant la propriété. Par exemple, identifiez l'objet est un Cat selon petType.

Toutefois, le champ discriminator n'est pas bien défini dans la spécification de la version actuelle ou dans les exemples (voir issue #403). Autant que je sache, il n'y a pas d'outils fournis par Swagger pour le moment.

discriminator peut être utilisé si le modèle a une propriété utilisée pour déterminer le type. Dans ce cas, il est naturellement adapté et il peut être utilisé comme un indicateur pour les autres développeurs de comprendre la relation de polymorphisme. Si des outils tiers tels que ReDoc qui prennent en charge discriminator (voir petType dans ce gif et example) sont pris en compte, cela peut vous être utile.

Answer 2

La fonctionnalité de discriminateur a été grandement améliorée dans OpenApi 3. Vous fournissez maintenant un objet discriminateur qui contient le nom de la propriété discriminator, ainsi qu'un mappage des valeurs de cette propriété aux noms de schéma.

(Je me rends compte que vous avez posé des questions sur OpenApi 2, mais il est tellement amélioré en 3 que vous pouvez l'utiliser).

Voir: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminatorObject pour la spécification réelle