web-dev-qa-db-fra.com

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

Référencement OpenAPI 2.0, objet schéma , ou Swagger 2.0, objet schéma , et la définition du champ discriminator comme:

Ajoute la prise en charge du polymorphisme. Le discriminateur est le nom de propriété de schéma utilisé pour différencier les autres schémas héritant de ce schéma. Le nom de propriété utilisé DOIT être défini dans ce schéma et il DOIT être dans la liste de propriétés required. Lorsqu'elle est utilisée, la valeur DOIT être le nom de ce schéma ou de tout schéma qui en hérite.

Mes confusions/questions:

  • Il est ambigu pour moi, quel rôle exactement il joue dans l'hérédité ou le polymorphisme. Quelqu'un pourrait-il expliquer 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 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), pour jouer avec cette propriété pour voir si je peux voir l'un de ses comportements spéciaux. J'ai changé la propriété, je l'ai supprimée et j'ai étendu le modèle Dog à un niveau plus profond et j'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- éditeur .
  • J'ai essayé de rechercher en ligne, et spécialement des questions de stackoverflow, mais je n'ai trouvé aucune information pertinente.

L'exemple de code que j'ai utilisé pour faire 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
swaggerswagger-2.0swagger-editoropenapiswagger-tools
22
Musa

Selon cela google group , discriminator est utilisé en plus de la propriété allOf et il est défini dans le super type 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 de composition.

Tout comme dans votre exemple de code, Pet est un super type avec la propriété petType identifié comme 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 vise à indiquer la propriété utilisée pour identifier le type d'un objet. Suppose qu'il existe des outils capables de prendre en charge correctement les objets de définition à l'aide 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.

Cependant, le champ discriminator n'est pas bien défini dans la spécification de la version actuelle ou les exemples (voir problème # 4 ). Pour autant que je sache, aucun outil fourni par Swagger ne le supporte correctement 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 en forme et peut être utilisé comme indicateur pour que d'autres développeurs comprennent la relation de polymorphisme. Si des outils tiers comme ReDoc qui prennent en charge discriminator (voir petType dans ce gif et exemple ) est considéré, vous pouvez trouver cela utile.

10
Wilson

La fonctionnalité de discriminateur a été considérablement améliorée dans OpenApi 3. Vous fournissez maintenant un objet discriminateur qui contient le nom de la propriété discriminante, 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 cela est tellement amélioré dans 3 que j'espère que vous pourrez vous en servir).

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

5
natke