Utiliser un Discriminator pour Adapter les Structures de Paramètres par Type dans Apidog

Dans notre précédent article "Que faire lorsque l'API a plusieurs structures de paramètres", nous avons abordé le fait que lorsqu'une API nécessite différentes structures de paramètres, vous pouvez utiliser oneOf, anyOf ou allOf dans Apidog pour les définir.

Une fois que vous avez configuré les structures de paramètres à l'aide de ces compositions de schémas, et que vos paramètres incluent un champ qui identifie le type de données, vous pouvez rendre la documentation encore plus claire en utilisant la fonctionnalité discriminator de la spécification OpenAPI pour distinguer les schémas de manière plus intuitive.

Qu'est-ce que le Discriminator ?

Dans OpenAPI, le rôle de discriminator est d'implémenter le "polymorphisme" de la programmation orientée objet.

En termes simples, il utilise une propriété partagée et sa valeur unique pour indiquer clairement quel schéma spécifique dans la liste oneOf ou anyOf doit être utilisé.

Par exemple, dans une animalerie, nous devons utiliser un schéma pour décrire les animaux de compagnie. (Et les chats et les chiens ont des propriétés différentes.)

Le schéma pour les chiens est :

{

    "name": "Hotdog",

    "age": 3,

    "weight": 25.5,

    "petType": "dog",

    "breed": "Golden Retriever",

    "isVaccinated": true,

    "walkingSchedule": "Morning and Evening",

    "favoriteToys": ["Frisbee", "Tennis Ball"],

    "trainingLevel": "Intermediate"

}

Le schéma pour les chats est :

{

    "name": "Meow",

    "age": 2,

    "weight": 4.2,

    "petType": "cat",

    "isVaccinated": true,

    "isIndoor": true,

    "litterBoxType": "Enclosed",

    "scratchingPostHeight": 120,

    "favoriteSleepingSpot": "Balcony"

}

Comme vous pouvez le constater, bien que les deux schémas aient des champs communs comme petType, name, age, etc., les chiens ont des champs spécifiques comme breed, walkingSchedule, etc., tandis que les chats ont des champs spécifiques comme isIndoor, litterBoxType, etc.

Si vous utilisez uniquement oneOf pour définir ces schémas lors de la conception de votre documentation API, la documentation peut techniquement distinguer les schémas dog et cat. Cependant, la correspondance de chaque type n'est pas très claire. Les lecteurs doivent basculer entre les deux onglets de schéma pour les comparer, ce qui devient déroutant lorsqu'il y a de nombreux paramètres.

utiliser oneOf pour définir plusieurs schémas

En ajoutant un discriminator, la documentation affichera un menu déroulant, où les lecteurs pourront choisir la valeur de petType (dog ou cat). Une fois sélectionnée, la page affichera automatiquement le schéma correct avec les champs pertinents. Cela élimine le besoin de comparer plusieurs onglets et rend les différences entre chaque schéma beaucoup plus claires.

le discriminateur rend les schémas plus clairs

Un discriminator est généralement utilisé conjointement avec oneOf ou anyOf. Le oneOf définit les schémas d'objets possibles, et le discriminator indique à l'analyseur comment déterminer quel schéma appliquer en fonction du type sélectionné.

Cela rend les objets complexes plus clairs et aide les outils à distinguer automatiquement les types lors du rendu de la documentation ou de la génération de code.

Propriétés de configuration de `discriminator`

Un discriminator contient deux propriétés clés :

propertyName : Spécifie le nom du champ utilisé pour distinguer les types, tel que petType dans l'exemple ci-dessus.
mapping : Définit la relation de mappage entre les valeurs de champ et les schémas spécifiques, tel que "dog" correspondant au schéma de chien et "cat" correspondant au schéma de chat.

Exemple de configuration dans OpenAPI :

discriminator:
  propertyName: petType
  mapping:
    dog: '#/components/schemas/Dog'
    cat: '#/components/schemas/Cat'

Configuration du Discriminator dans Apidog

Apidog prend en charge la configuration de discriminator de deux manières :

Interface graphique (GUI) + Schéma JSON
Importation directe des spécifications OpenAPI

Méthode 1 : Interface graphique (GUI) + Schéma JSON

Tout d'abord, créez les schémas dans Apidog, tels que Dog et Cat :

Ouvrez le point de terminaison où vous souhaitez utiliser ces schémas et accédez à l'éditeur de corps de requête ou de réponse.

Sélectionnez le champ que vous souhaitez définir comme composition de schéma et choisissez Advanced Settings → Schema Compositions → oneOf.

Dans oneOf, référencez les schémas dont vous avez besoin, tels que Dog et Cat.

référencer les schémas pour les compositions de schémas oneOf

Vous avez maintenant défini plusieurs schémas possibles via oneOf. Ensuite, vous devez ajouter discriminator pour spécifier comment distinguer ces schémas. Cliquez sur JSON Schema pour passer en mode code :

Ajoutez la configuration discriminator à l'emplacement approprié (au même niveau que oneOf), par exemple :

"discriminator": {
    "propertyName": "petType",
    "mapping": {
        "dog": "#/definitions/190704823",
        "cat": "#/definitions/190704706"
    }
}

Les valeurs dans mapping, telles que #/definitions/190704823, sont des identifiants uniques générés en interne par Apidog pour les schémas. Vous pouvez trouver le chemin definitions correspondant pour chaque schéma dans le panneau de configuration du schéma JSON.

Panneau de configuration du schéma JSON dans Apidog

Une fois la configuration terminée, enregistrez-la. Dans la documentation de l'API, vous pouvez basculer intelligemment entre les types d'objets en fonction de la valeur du champ petType.

Méthode 2 : Importation directe des spécifications OpenAPI

C'est une approche plus standard, particulièrement adaptée aux équipes habituées aux workflows "design-first".

Rédigez vos spécifications OpenAPI en incluant discriminator, puis importez-les dans Apidog.

Par exemple, dans les spécifications OpenAPI, la définition de discriminator est la suivante :

Pet:
  oneOf:
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Cat'
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      cat: '#/components/schemas/Cat'

Cette définition indique clairement :

Via oneOf, spécifier que l'objet peut être de type Dog ou Cat
Via discriminator, spécifier la détermination du type spécifique en fonction de la valeur du champ petType
Via mapping, spécifier clairement que "dog" correspond au schéma Dog et "cat" correspond au schéma Cat.

Les spécifications OpenAPI complètes sont les suivantes :

openapi: 3.0.3
info:
  title: Pet Shop API
  version: 1.0.0

components:
  schemas:
    Dog:
      type: object
      properties:
        petType:
          type: string
          enum: [dog]
        name:
          type: string
        age:
          type: integer
        weight:
          type: number
        breed:
          type: string
        isVaccinated:
          type: boolean
        walkingSchedule:
          type: string
        favoriteToys:
          type: array
          items:
            type: string
        trainingLevel:
          type: string
      required:
        - petType
        - name
        - age

    Cat:
      type: object
      properties:
        petType:
          type: string
          enum: [cat]
        name:
          type: string
        age:
          type: integer
        weight:
          type: number
        isVaccinated:
          type: boolean
        isIndoor:
          type: boolean
        litterBoxType:
          type: string
        scratchingPostHeight:
          type: integer
        favoriteSleepingSpot:
          type: string
      required:
        - petType
        - name
        - age

    Pet:
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Cat'
      discriminator:
        propertyName: petType
        mapping:
          dog: '#/components/schemas/Dog'
          cat: '#/components/schemas/Cat'

paths:
  /pets:
    get:
      summary: Get pet information
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

Après avoir complété les spécifications OpenAPI, utilisez la fonction d'importation dans Apidog. Apidog analysera toutes les spécifications, créera automatiquement les schémas et les points de terminaison correspondants, et reconnaîtra correctement la configuration discriminator (enum est ajouté ici pour verrouiller les valeurs des paramètres).

importer OpenAPI pour ajouter un discriminateur afin de distinguer plusieurs schémas

FAQ

1. Quand utiliser un Discriminator ?

Vous ne devez utiliser un discriminator que si votre point de terminaison inclut déjà un champ qui identifie les schémas. Dans l'exemple ci-dessus, le champ petType existe dans la conception de l'API et est utilisé pour différencier les types d'animaux de compagnie.

Le discriminator indique simplement aux outils comment choisir le schéma correct en fonction de la valeur de ce champ.

Si votre point de terminaison n'inclut pas un tel champ d'identification de type, alors un discriminator n'est pas approprié — l'utilisation de oneOf seul est suffisante.

De plus, si votre schéma est simple ou ne présente que quelques variations, vous n'aurez peut-être pas du tout besoin d'un discriminateur.

2. Le Discriminator doit-il être utilisé avec oneOf ?

Oui. Un discriminateur doit être utilisé conjointement avec oneOf, anyOf ou allOf. Il ne peut pas définir de schémas seul — il explique seulement comment distinguer plusieurs schémas possibles.

Conclusion

discriminator est une fonctionnalité optionnelle de la spécification OpenAPI utilisée pour améliorer l'expérience utilisateur de oneOf/anyOf/allOf.

Lorsque vos spécifications de point de terminaison contiennent déjà des champs utilisés pour identifier les types, vous pouvez configurer discriminator dans Apidog pour rendre la documentation API plus claire et plus intelligente.

Bien sûr, si vous trouvez la configuration fastidieuse ou si le schéma est relativement simple, vous pouvez tout à fait n'utiliser que des compositions de schémas comme oneOf.