Tester les points de terminaison avec Try It !

Try It ! est la console API interactive de Document360, intégrée directement dans votre référence API publiée. Cela permet aux développeurs d’envoyer de vraies requêtes à vos points d’accès API et de voir les réponses en temps réel sans quitter la documentation ni écrire de code.

Cet article explique comment fonctionne la console Try It ! dans votre référence d’API publiée — comment l’ouvrir, construire et envoyer une requête, lire la réponse, et ce que la console supporte ou non. Pour plus de détails sur la configuration de chaque méthode d’authentification, voir Autoriser les requêtes dans la console Essay.

Qu’est-ce que Try It fait !

Depuis n’importe quelle page endpoint dans votre référence API publiée, les développeurs peuvent :

• Ouvrez une console interactive en ligne sur le point d’extrémité, sans quitter la page
• Remplir les paramètres de chemin et de requête, les en-têtes, et (pour les méthodes d’écriture) un corps de requête
• Fournir les identifiants d’authentification pour le schéma de sécurité du point de terminaison
• Envoyez une demande en direct et consultez la véritable réponse — statut, timing, en-têtes et corps

Ouverture de la console Try It

Sur n’importe quelle page de point d’extrémité, la méthode et l’URL du point de terminaison apparaissent en haut, avec un bouton Essayer à côté.

1. Cliquez sur Essayer. La console interactive s’ouvre en ligne, juste en dessous de l’URL du point de terminaison.
2. Construisez votre requête en utilisant les onglets décrits ci-dessous, puis cliquez sur Envoyer.
3. Quand vous avez terminé, cliquez sur l’icône « Fermer essayer » (X) pour faire replier la console et revenir à la lecture de la documentation.

La console s’ouvre sur place – vous restez sur la même page de terminaison tout le temps, avec la documentation toujours visible au-dessus.

Création d’une demande

Le générateur de requêtes est organisé en onglets. Les onglets qui apparaissent dépendent de la méthode HTTP du point d’accès :

• Params — paramètres de chemin et de requête définis pour le point de terminaison. Les paramètres requis sont indiqués, et chacun affiche sa description à partir de votre spécification.
• Autorisation — la méthode d’authentification et les champs d’identification pour le schéma de sécurité du point de terminaison. Voir Autoriser les requêtes dans la console Essayer.
• En-têtes — en-têtes de demande.
• Corps — la charge utile de la requête. Cet onglet apparaît uniquement pour les méthodes qui nécessitent un corps, telles que POST, PUT et PATCH. Il n’est pas affiché pour les demandes GET.

Au fur et à mesure que vous remplissez les onglets, la console crée la requête en arrière-plan. Vous pouvez prévisualiser la requête assemblée à tout moment dans le panneau Requêtes à droite, et voir l’exemple de code équivalent dans le panneau de code .

Collaboration avec l’organisme demandeur

Pour les terminaux qui acceptent un corps, l’onglet Corps vous offre un éditeur complet avec des outils pour construire et valider votre charge utile.

• Aucun / RAW — Choisissez d’envoyer None Body (none) ou une charge utile brute (raw).
• Type de média — sélectionnez le type de contenu pour le corps, comme application/json.
• Exemple — insérez une charge utile d’exemple prête à l’emploi pour le point de terminaison, générée à partir de votre spécification.
• Remplir à partir du schéma — remplir l’éditeur avec un corps d’exemple construit à partir du schéma de requête du terminaison. Cela écrase le contenu actuel de l’éditeur.
• Embellir — reformater le corps avec une indentation appropriée, rendant une charge utile minfiée ou désordonnée lisible.
• Restaurez un corps récemment envoyé — ramenez un corps que vous avez envoyé plus tôt dans cette séance. Cela restaure les corps que vous avez effectivement envoyés, vous permettant de revenir rapidement à une charge utile précédente sans la retaper.
• Basculez le « word wrap » — enroulez de longues lignes dans l’éditeur pour pouvoir les lire sans avoir à faire défiler horizontalement.

Validation par rapport au schéma

L’éditeur de corps valide votre charge utile par rapport au schéma du point de terminaison au fur et à mesure que vous tapez — pas seulement pour le JSON valide, mais aussi pour savoir si la charge utile correspond réellement à ce que le point de terminaison attend.

Cela détecte deux types de problèmes différents :

• Erreurs de syntaxe — la charge utile n’est pas bien formée, par exemple une virgule ou un deux-points manquants. Celles-ci apparaissent sous forme de messages tels que « Deux-points attendu » ou « Virgule attendue ».
• Erreurs de schéma — la charge utile est un JSON valide mais ne correspond pas au schéma. Par exemple, si un champ attend un entier et que vous fournissez une chaîne, l’éditeur marque « Type incorrect. Attendu... ». Fournir un champ que le schéma n’autorise pas est signalé comme « Propriété n’est pas autorisée ».

Lorsque des problèmes sont détectés, une zone de validation du corps apparaît sous l’éditeur, affichant un décompte des problèmes. Utilisez le problème Passer au problème suivant pour aller directement à chacun dans l’éditeur, et développez la liste pour voir tous les problèmes en même temps.

Cela signifie qu’une charge utile peut être parfaitement valide en JSON et rester signalée — car Try It ! la compare au schéma réel de votre API, détectant les incompatibilités avant que vous envoyiez la requête plutôt qu’après que le serveur l’ait rejetée.

Envoi de la demande et lecture de la réponse

Une fois votre demande prête, cliquez sur Envoyer la demande. La console envoie une requête en direct à votre API et affiche le résultat dans la zone de réponse à droite.

La réponse comprend :

• Statut — le code d’état HTTP retourné, tel que 200, 401, ou 404.
• Le temps — combien de temps a pris la demande, en millisecondes.
• Taille — la taille du corps de réponse.
• Onglets corps et en-tête — alternez entre la charge utile de réponse et l’ensemble complet des en-têtes de réponse renvoyés par le serveur.

Vous pouvez redimensionner les panneaux de requête et de réponse en faisant glisser le séparateur entre eux, ce qui laisse plus de place à chaque côté où vous travaillez.

Votre travail est sauvegardé

Pendant que vous travaillez sur la console, Try It ! conserve vos entrées afin que vous ne les perdiez pas en vous déplaçant :

• Les paramètres, les en-têtes, le corps de la requête, le type de média sélectionné et l’onglet actif sont conservés lorsque vous changez de point de terminaison et même si vous fermez et rouvrez la console pendant la même session.
• Les identifiants et la dernière réponse sont conservés uniquement pour la session active et ne sont pas maintenus. Les identifiants sont également masqués dans l’aperçu des requêtes pour des raisons de sécurité.

Authentification

Les développeurs fournissent les identifiants dans l’onglet Authorization , en utilisant le schéma défini par votre API — clé API, HTTP Basic, HTTP Bearer, OAuth 2.0 ou OpenID Connect. Try It ! lit les schémas de votre spécification OpenAPI et affiche les champs corrects pour chacun.

Pour tous les détails sur chaque méthode — y compris la façon de les définir dans votre spécification et le fonctionnement de la connexion OAuth 2.0 dans la console — voir Autoriser les requêtes dans la console Essayer.

Utilisation des variables

Les variables permettent aux développeurs de stocker une valeur une fois et de la réutiliser entre les points de terminaison avec un {{placeholder}} — utile pour des valeurs comme un ID ou un jeton qui se répètent sur de nombreuses requêtes. Vous pouvez insérer une variable dans n’importe quel champ, et l’aperçu de la requête montre qu’elle a été résolue à sa valeur réelle.

Pour savoir comment créer, gérer et réutiliser des variables, voir Utiliser les variables dans la console Essaie.

Exigences pour que Try It ! apparaisse

Try It ! n’apparaît sur une page de terminaison que lorsque votre fichier de spécification API définit correctement ce qui suit :

• Une URL serveur - la servers section de votre spécification doit contenir au moins une URL de base valide.
• Une variable serveur (optionnelle) - si utilisée , la variable doit être définie en même temps que l’URL.

Si l’URL du serveur manque, le bouton Essayer ! ne sera pas visible sur le site de la base de connaissances.

Format correct de l’URL serveur

servers:
  - url: https://api.yourdomain.com
    description: Production

Pour les API à plusieurs régions, définissez plusieurs entrées :

servers:
  - url: https://api.yourdomain.com
    description: Global

  - url: https://api.us.yourdomain.com
    description: US region

Qu’est-ce que Try It ! ne prend pas en charge

• Webhooks - Try It ! n’est pas disponible pour les définitions de webhooks. Les pages Webhook montrent le schéma de la charge utile et un exemple mais ne peuvent pas envoyer de requêtes de test.

FAQ