Les paramètres d'API ont souvent des structures complexes, un seul point d'accès prenant en charge plusieurs combinaisons de paramètres différentes. Par exemple, un point d'accès de connexion pourrait prendre en charge l'authentification par nom d'utilisateur et mot de passe, l'authentification par e-mail et mot de passe, ou les codes de vérification par numéro de téléphone. Les points d'accès de paiement peuvent offrir diverses méthodes comme les cartes de crédit, WeChat Pay ou Alipay, chacune nécessitant des champs différents.
Les approches traditionnelles de documentation API se contentent souvent de lister tous les champs possibles et d'utiliser des descriptions textuelles telles que "choisir différents champs en fonction de différents scénarios". Cette approche n'est ni précise ni conviviale pour les développeurs, et conduit souvent à la confusion. Apidog prend en charge les fonctionnalités oneOf, anyOf et allOf de JSON Schema, vous permettant de décrire avec précision ces structures de données composites complexes dans votre documentation API.
Comprendre les trois modes de combinaison
Dans JSON Schema, oneOf, anyOf et allOf sont utilisés pour combiner plusieurs sous-schémas, mais ils ont des significations logiques différentes :
- allOf : Combine plusieurs règles, exigeant que toutes correspondent
- anyOf : Au moins une correspondance est requise, plusieurs correspondances sont acceptables
- oneOf : Doit correspondre exactement à un schéma ; une correspondance nulle ou multiple échouera
Configurer les modes de combinaison dans Apidog
Apidog propose deux façons d'utiliser ces modes de combinaison :
Approche de l'éditeur visuel
La première méthode utilise le panneau d'édition visuelle. Dans votre projet, cliquez sur "Modèles de données" pour créer un nouveau modèle, puis trouvez "Modes de combinaison" dans la sélection de type. Choisissez le mode oneOf, anyOf ou allOf nécessaire, puis définissez des structures de données spécifiques pour chaque sous-schéma.
Éditeur de code JSON Schema
La deuxième approche consiste à éditer directement le code JSON Schema. Dans le panneau d'édition du modèle de données, vous pouvez passer en mode code et écrire directement du JSON Schema pour définir ces modèles de combinaison logique. Cette méthode est plus directe pour les développeurs familiers avec JSON Schema.
Application de ces modèles dans les points d'accès API
Une fois que vous avez défini vos modèles de données, vous pouvez les utiliser dans votre documentation API. Lors de l'édition des paramètres de requête d'interface, sélectionnez le type de corps JSON, puis dans la section de la structure des données, vous pouvez référencer les "Modèles de données" que vous venez de créer, ou sélectionner directement "Modes de combinaison" pour définir des structures de paramètres complexes.
Le même principe s'applique aux définitions de données de réponse. Lorsque vous ajoutez des exemples de réponse dans la section de réponse, vous pouvez utiliser des modes de combinaison pour décrire les formats de réponse pour différents scénarios. De cette façon, les développeurs peuvent clairement comprendre quelle structure de données sera renvoyée dans différentes situations.
Cas d'utilisation réels
allOf : Combinaison de plusieurs structures
allOf combine plusieurs structures ensemble – il ne s'agit pas de sélection, mais d'empilement. allOf ne modifie pas la hiérarchie des champs ; tous les champs se retrouvent dans le même objet. Il empile simplement plusieurs règles sur les mêmes données. Considérez-le comme un "ET logique" – toutes les contraintes de sous-structure doivent être satisfaites.
Par exemple, ce JSON Schema :
{
"allOf": [
{
"description": "Informations utilisateur de base",
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
},
{
"description": "Informations de contact",
"type": "object",
"properties": {
"email": { "type": "string", "format": "email" },
"phone": { "type": "string" }
},
"required": ["email"]
}
]
}
Ce schéma signifie : les données finales doivent satisfaire simultanément les structures "informations utilisateur de base" et "informations de contact".
En d'autres termes, le corps de la requête doit inclure l'identifiant (id), le nom (name) et l'e-mail (email), tandis que le téléphone (phone) est facultatif.
Données valides :
{
"id": 1001,
"name": "John Doe",
"email": "john@example.com",
"phone": "1-800-000-0000"
}
Données invalides :
{
"id": 1001,
"name": "John Doe"
}
Ceci manque le champ d'e-mail requis et ne satisfait pas la deuxième structure.
Cette approche convient pour diviser des objets complexes. Les informations utilisateur, les détails de commande, les éléments de configuration, etc., peuvent tous être divisés en structures indépendantes par modules fonctionnels, puis combinés à l'aide de allOf. D'autres interfaces qui ont besoin d'une partie de ces structures peuvent les référencer directement sans définitions redondantes.
anyOf : Satisfaire au moins une condition
anyOf liste plusieurs structures possibles, et les données sont considérées comme valides tant qu'elles sont conformes à au moins l'une d'entre elles. Il ne se soucie pas de savoir si plusieurs conditions sont satisfaites, ni n'exige une correspondance unique.
Par exemple, un champ d'identifiant peut être un e-mail ou un numéro de téléphone. Ces deux formats sont distinctement différents, mais tous deux appartiennent à la catégorie des "identifiants de connexion utilisateur".
Vous pouvez utiliser anyOf pour exprimer clairement cette intention "peut être A ou B" :
{
"type": "object",
"properties": {
"identifier": {
"description": "Identifiant utilisateur : peut être un e-mail ou un numéro de téléphone",
"anyOf": [
{
"title": "Format e-mail",
"description": "Doit être une adresse e-mail valide",
"type": "string",
"format": "email"
},
{
"title": "Format téléphone",
"description": "Doit être un numéro de téléphone international valide",
"type": "string",
"pattern": "^\\+?[1-9]\\d{1,14}$"
}
]
},
"password": {
"type": "string",
"minLength": 6,
"description": "Mot de passe de connexion, au moins 6 caractères"
}
},
"required": ["identifier", "password"],
"description": "Paramètres de requête de connexion utilisateur"
}
Cette structure signifie : l'identifiant est une chaîne de caractères considérée comme valide tant qu'elle satisfait soit le format e-mail, soit le format numéro de téléphone.
Données valides :
{
"identifier": "test@example.com",
"password": "123456"
}
{
"identifier": "+1-800-000-0000",
"password": "123456"
}
Données invalides :
{
"identifier": "abc",
"password": "123456"
}
"abc" n'est ni un e-mail ni un format de numéro de téléphone valide, ne satisfaisant aucune des conditions.
oneOf : Choisir exactement une option
oneOf liste plusieurs structures possibles, et les données doivent se conformer exactement à l'une d'entre elles. Il met l'accent sur l'exclusivité – vous ne pouvez en choisir qu'une, ni plus, ni moins.
Par exemple, les méthodes de paiement : pour effectuer un paiement, les utilisateurs doivent choisir l'une des options suivantes : carte de crédit, WeChat Pay ou Alipay, mais ne peuvent pas utiliser deux méthodes simultanément, ni n'en choisir aucune. Vous pouvez définir cette logique de "choix unique" à l'aide de oneOf :
{
"properties": {
"paymentMethod": {
"description": "Méthode de paiement, doit en choisir exactement une",
"oneOf": [
{
"title": "Paiement par carte de crédit",
"description": "Payer par carte de crédit, nécessite le numéro de carte et la date d'expiration",
"type": "object",
"properties": {
"type": { "const": "credit_card" },
"cardNumber": { "type": "string" },
"expiryDate": { "type": "string" }
},
"required": ["type", "cardNumber", "expiryDate"],
"additionalProperties": false
},
{
"title": "Paiement WeChat",
"description": "Payer via WeChat, nécessite l'openid de l'utilisateur",
"type": "object",
"properties": {
"type": { "const": "wechat" },
"openid": { "type": "string" }
},
"required": ["type", "openid"],
"additionalProperties": false
},
{
"title": "Paiement Alipay",
"description": "Payer via Alipay, nécessite l'ID de compte",
"type": "object",
"properties": {
"type": { "const": "alipay" },
"accountId": { "type": "string" }
},
"required": ["type", "accountId"],
"additionalProperties": false
}
]
}
}
}
Cette définition signifie : `paymentMethod` est un objet qui ne peut correspondre qu'à l'une des trois sous-structures.
Exemples valides :
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123456"
}
}
{
"paymentMethod": {
"type": "credit_card",
"cardNumber": "4111111111111111",
"expiryDate": "12/25"
}
}
Exemple invalide :
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123",
"accountId": "2088102"
}
}
Même si le type est "wechat", la présence de `accountId` pourrait le faire correspondre à plusieurs structures, ce qui entraînerait l'échec de `oneOf`. L'ajout de `"additionalProperties": false` empêche cette confusion (signifiant qu'aucun champ supplémentaire n'est autorisé), garantissant que chaque structure n'autorise que ses propres champs définis. Apidog prend en charge la configuration visuelle des propriétés additionnelles.
Lorsque vous devez faire des choix exclusifs entre plusieurs types distincts, `oneOf` est le moyen le plus direct et le plus fiable d'exprimer cela.
Choisir le bon mode de combinaison
Le choix du mode de combinaison dépend principalement de votre logique métier :
- Utilisez allOf lorsque vous avez besoin de combiner et d'hériter de plusieurs modèles
- Utilisez anyOf lorsque vous avez besoin de combinaisons optionnelles flexibles
- Utilisez oneOf lorsque vous avez besoin de choix exclusifs stricts
Comprendre leurs rôles respectifs permet à votre documentation API de décrire avec précision des structures de données complexes, rendant immédiatement clair pour les utilisateurs de l'interface comment passer les paramètres.
Conclusion
La prise en charge complète de JSON Schema par Apidog permet aux développeurs de créer une documentation API précise et claire, même pour les structures de paramètres les plus complexes. En tirant parti des combinaisons oneOf, anyOf et allOf, vous pouvez éliminer l'ambiguïté et fournir des directives limpides aux consommateurs d'API.
Prêt à découvrir la puissance d'une documentation API avancée ? Essayez Apidog dès aujourd'hui et voyez à quel point il devient facile de gérer des paramètres API complexes avec précision et clarté.