Lorsque vous ouvrez un document d'API en ligne publié avec Apidog, vous remarquerez un bouton "Essayer" à côté de chaque point d'accès (endpoint). En cliquant dessus, un panneau de débogage s'affiche sur le côté droit de la page, vous permettant de tester l'API directement depuis la documentation.
Cependant, l'utilisabilité de cette fonctionnalité de "Débogage" dépend largement de la manière dont vous l'avez configurée au sein de la plateforme. Des facteurs tels qu'une configuration d'URL appropriée, une configuration d'authentification, une structure de paramètres claire et des données d'exemple complètes ont un impact significatif sur l'expérience de débogage.
Si elle n'est pas configurée correctement, les utilisateurs risquent de passer beaucoup de temps à remplir des paramètres ou même de ne pas réussir à effectuer des appels d'API, ce qui est loin d'être idéal.
Discutons de la manière de configurer Apidog efficacement pour garantir que la documentation en ligne publiée offre une excellente expérience de débogage.
Configuration d'URL appropriée
Souvent, la documentation en ligne semble correcte, mais échoue lorsque vous cliquez sur le bouton "Essayer" pour envoyer une requête. La raison la plus courante est que le point d'accès n'inclut qu'un chemin comme /pet/{petId} sans sélectionner d'environnement d'exécution lors de la publication.
Cela se traduit par des URL de requête incomplètes, sans protocole ni nom d'hôte, entraînant des erreurs lors de l'envoi des requêtes.
Pour y remédier, assurez-vous que les utilisateurs peuvent accéder à la bonne URL. Apidog propose trois façons de configurer les URL pour la documentation en ligne, selon vos besoins.
1. Utiliser les URL de base
C'est l'approche recommandée. Définissez uniquement le chemin dans le point d'accès, tel que /pet/{petId}, et configurez l'adresse complète du service (par exemple, https://product.example.com) dans la section "Gestion de l'environnement" comme URL de base.
Lors de la publication de la documentation API, sélectionnez l'environnement d'exécution approprié. Apidog concaténera automatiquement l'URL de base avec le chemin du point d'accès. Vous pouvez également définir plusieurs environnements d'exécution, chacun avec sa propre URL de base.
Dans la documentation en ligne, les utilisateurs peuvent rapidement changer d'environnement à partir d'une liste déroulante, et toutes les URL des points d'accès seront mises à jour en conséquence. Cela facilite la validation des API dans différents environnements.
Remarque : Soyez attentif aux problèmes de protocole. De nombreux navigateurs empêchent les pages HTTPS d'appeler des API HTTP. Si votre API utilise HTTP, les utilisateurs peuvent rencontrer des problèmes de protocole croisé lors du débogage sur une page de documentation HTTPS.
2. Inclure les URL complètes dans les points d'accès
Une autre option consiste à spécifier l'URL complète directement dans le point d'accès, par exemple https://product.example.com/pet/{petId}.
Cela garantit que l'URL de requête complète est visible quel que soit l'environnement d'exécution sélectionné. Cependant, la gestion des modifications d'adresses de serveur devient fastidieuse car vous devrez mettre à jour chaque point d'accès individuellement. Par conséquent, cette méthode est moins recommandée.
3. Utiliser des variables dans les URL
Si vous souhaitez que les utilisateurs personnalisent l'URL pour le débogage, vous pouvez utiliser des variables. Par exemple, créez une variable d'environnement BaseURL dans la section "Gestion de l'environnement" et référencez-la dans l'URL de base comme {{BaseURL}}.
Dans la documentation en ligne, les utilisateurs peuvent cliquer sur le nom de la variable et la modifier pour obtenir l'URL souhaitée.
Alternativement, vous pouvez définir des variables directement dans le point d'accès, tel que {{BaseURL}}/pet/{petId}.
Pour ce point d'accès spécifique dans la documentation en ligne, les utilisateurs peuvent définir la valeur de la variable pour envoyer la requête.
Avant de publier la documentation, assurez-vous que les "valeurs initiales" dans l'environnement ne contiennent pas d'informations sensibles (par exemple, des identifiants d'authentification), car ces valeurs seront incluses dans la documentation publiée et pourraient présenter des risques pour la confidentialité.
Configuration d'authentification appropriée
Configuration de l'authentification de base
Les requêtes de point d'accès réussies nécessitent souvent une authentification. Apidog prend en charge différents types d'authentification, notamment le Jeton Bearer, la Clé API, OAuth2.0 et l'Authentification de base.
Vous pouvez configurer l'authentification au niveau du point d'accès ou du dossier en utilisant un schéma de sécurité ou en la configurant manuellement.
Par exemple, lors de l'utilisation du Jeton Bearer comme type d'authentification, un champ "Jeton" apparaît en haut du panneau de débogage dans la documentation en ligne. Les utilisateurs peuvent saisir directement la valeur du jeton sans ajouter manuellement le préfixe "Bearer". Apidog gère cela automatiquement, ce qui est plus pratique que d'ajouter un en-tête d'autorisation manuellement.
L'avantage de cette configuration est que les informations d'authentification peuvent être partagées entre plusieurs points d'accès. Si plusieurs points d'accès utilisent le même schéma ou type de sécurité, il vous suffit de saisir les identifiants une seule fois. Toute mise à jour des identifiants s'appliquera automatiquement à tous les points d'accès associés.
Les identifiants d'authentification sont chiffrés et stockés localement dans le navigateur de l'utilisateur, gérés par session et partagés entre les onglets et les fenêtres. Ils sont effacés à la fermeture du navigateur, réduisant ainsi le risque d'exposition d'informations sensibles dans la documentation publiée.
Configuration OAuth2.0
Pour l'authentification OAuth2.0, si vous souhaitez que les utilisateurs génèrent des jetons directement pendant le débogage, configurez les détails du serveur d'autorisation (par exemple, URL d'authentification, URL de jeton) dans le projet.
Lors de l'utilisation du schéma de sécurité OAuth2.0, les utilisateurs devront saisir l'ID client, le secret client, etc., pendant le débogage. Une fenêtre contextuelle les guidera à travers le processus d'autorisation, et l'access_token obtenu sera automatiquement appliqué aux requêtes API ultérieures.
Concevoir des structures de paramètres claires
Affichage des paramètres dans le panneau de débogage
Le panneau de débogage affiche intelligemment les sections de paramètres en fonction de la conception de votre point d'accès. Par exemple, si le point d'accès ne définit que des paramètres de chemin (Path parameters), le panneau de débogage n'affichera que la section Chemin, évitant ainsi les sections de Requête (Query) ou de Corps (Body) inutiles.
Cette clarté aide les utilisateurs à comprendre quels paramètres remplir sans être distraits par des sections non pertinentes.
Fournir des exemples
Lors de la conception des points d'accès, définissez précisément le type et les attributs requis de chaque paramètre. Incluez des descriptions claires et des exemples, car ceux-ci seront pré-remplis dans le panneau de débogage, améliorant ainsi l'utilisabilité.
Éviter les en-têtes redondants
Si le point d'accès définit des paramètres de corps (Body parameters), il n'est pas nécessaire d'ajouter manuellement des en-têtes comme Content-Type: application/json. Apidog gère automatiquement ces en-têtes lors des requêtes.
De même, si l'authentification est configurée, évitez de la dupliquer dans les en-têtes. Les paramètres d'authentification ont la priorité et annuleront toute configuration d'en-tête conflictuelle.
Proposer des exemples de requêtes complets
Pour les points d'accès avec des corps de requête JSON complexes, fournissez plusieurs exemples de corps de requête lors de la conception.
Les utilisateurs peuvent sélectionner ces exemples à partir d'un menu déroulant dans le panneau de débogage, ce qui permet de gagner du temps et de réduire les erreurs.
Assurez-vous que les données d'exemple ressemblent étroitement à des scénarios réels, mais évitez d'inclure des informations sensibles. Les utilisateurs peuvent modifier ces exemples si nécessaire.
Configurer des exemples de réponses clairs
Après l'envoi d'une requête, le panneau de débogage affiche la réponse complète, y compris les codes de statut, les en-têtes et le corps. En tant que créateur de documentation, configurez des exemples de réponses clairs pour aider les utilisateurs à comprendre les résultats possibles.
Fournissez plusieurs exemples de réponses pour chaque point d'accès, tels que succès (200), mauvaise requête (400) et non autorisé (401).
Portez une attention particulière aux réponses d'erreur, en expliquant clairement les codes d'erreur et les formats de message pour différents scénarios. Cela aide les utilisateurs à identifier et à résoudre rapidement les problèmes pendant le débogage.
Fournir des exemples de code pour l'intégration
Bien qu'Apidog génère automatiquement du code d'exemple pour les langages de programmation courants, le code généré peut ne pas correspondre entièrement à vos besoins métier. Dans de tels cas, personnalisez les exemples.
Vous pouvez configurer les langages pour lesquels des exemples auto-générés sont requis dans "Paramètres du projet -> Paramètres des fonctionnalités des points d'accès -> Exemples de code de requête".
De plus, vous pouvez écrire du code d'exemple personnalisé pour des points d'accès spécifiques dans la section "Description du point d'accès".
Cela garantit que les utilisateurs voient à la fois les exemples auto-générés et personnalisés dans la documentation en ligne, ce qui facilite l'intégration.
Résumé
L'expérience de débogage de la documentation en ligne dépend fortement d'une configuration appropriée. En configurant judicieusement les URL, l'authentification, les structures de paramètres et les exemples, vous pouvez vous assurer que les utilisateurs commencent rapidement à utiliser votre API sans être submergés par les détails techniques.