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 Try It !, ce dont les développeurs ont besoin pour l’utiliser, et comment configurer chaque méthode d’authentification prise en charge dans votre spécification API.
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 :
- Sélectionnez une méthode HTTP et un point de terminaison
- Paramètres de remplissage obligatoires et optionnels
- Configurer les identifiants d’authentification
- Envoyez une demande en direct et consultez la réponse en temps réel
Try It ! n’est pas disponible pour les 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.
Exigences pour que Try It ! apparaisse
Try It ! n’apparaît sur une page endpoint que lorsque les deux éléments suivants sont correctement définis dans votre fichier de spécifications API :
- Une URL serveur - la
serverssection de votre spécification doit contenir au moins une URL de base valide. - Une variable serveur - la variable doit être définie en même temps que l’URL.
Si l’un de ces éléments 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
Les URL ci-dessus en sont des exemples. Utilisez l’URL de base réelle de votre API.
Comment les requêtes sont acheminées
Quand un développeur clique sur Essayer et voir la réponse, l’URL de la demande sera tryit.document360.io ajoutée en pré-ajout à l’URL de base de votre API. Par exemple :
https://tryit.document360.io/https://api.yourdomain.com/v2/your-endpoint
C’est un comportement attendu. Le tryit.document360.io sous-domaine est utilisé en interne pour acheminer et traiter les requêtes de test de l’API. Cela n’affecte pas la fonctionnalité, mais les requêtes retournent toujours les bons résultats de votre API.
Méthodes d’authentification prises en charge
Document360 lit la configuration d’authentification directement depuis votre spécification OpenAPI et la présente en deux endroits : la documentation du point de terminaison et la console Try It !.
| Méthode | Comment ça fonctionne |
|---|---|
| Authentification de base | Nom d’utilisateur et mot de passe passés dans l’en-tête de la requête. |
| Jeton porteur | Un jeton généré après la connexion est passé dans l’en-tête d’Authorization. |
| Clé API | Une clé unique passait dans les en-têtes de requête. |
| OAuth2 | Prend en charge le code d’autorisation, le PKCE, les identifiants clients et les flux implicites. |
| OpenID Connect | Étend OAuth2 pour ajouter la vérification de l’identité utilisateur. |
Les méthodes d’authentification sont définies dans votre spécification OpenAPI sous components/securitySchemes et appliquées à chaque point de terminaison via le security champ.
Try It ! prend en charge plusieurs systèmes de sécurité simultanément. Cela signifie que les développeurs peuvent tester des points de terminaison nécessitant des méthodes d’authentification combinées au sein d’une même session.
Authentification de base
L’authentification de base nécessite qu’un nom d’utilisateur et un mot de passe soient codés et transmis dans l’en-tête Authorization de chaque requête.
Dans votre spécification OpenAPI :
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
Appliquez-le à un point de terminaison :
/your-endpoint:
get:
security:
- basicAuth: []
Dans Essayez !, les développeurs seront invités à saisir un nom d’utilisateur et un mot de passe avant d’envoyer une demande.
Jeton porteur
L’authentification du jeton porteur utilise un jeton passé dans l’en-tête Authorization comme Bearer <token>.
Dans votre spécification OpenAPI :
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
Document360 exige que le schéma de sécurité soit nommé BearerAuth (sensible à la casse). Si cette définition manque dans votre spécification, cliquer sur Essayer ! sur un point de terminaison affecté reviendra une erreur 403. Lors de l’importation, Document360 signalera cela dans la section Alertes s’il détecte une définition manquante de BearerAuth.
Appliquez-le à un point de terminaison :
/your-endpoint:
get:
security:
- BearerAuth: []
Clé API
L’authentification par clé API utilise une clé unique passée dans les en-têtes de requête.
Dans votre spécification OpenAPI :
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
Appliquez-le à un point de terminaison :
/your-endpoint:
get:
security:
- ApiKeyAuth: []
Dans Try It !, les développeurs seront invités à saisir la valeur de leur clé API. Il sera envoyé dans le nom d’en-tête défini dans votre spécification (X-API-Key dans l’exemple ci-dessus).
OAuth2
OAuth2 est supporté par quatre flux. Utilisez le flux qui correspond à la façon dont votre API émet les jetons d’accès.
| Écoulement | Quand l’utiliser |
|---|---|
| Code d’autorisation | Les applications côté serveur où le secret client peut rester confidentiel. |
| PKCE | Des clients publics tels que les applications à page unique et les applications mobiles où le secret ne peut être gardé confidentiel. |
| Références clients | Communication machine à machine où aucun utilisateur n’est impliqué. |
| Implicite | Flux hérité. Ce n’est pas recommandé pour les nouvelles implémentations. |
Configuration requise pour Try It !
Lorsque votre API utilise OAuth2, deux paramètres supplémentaires doivent être configurés :
Redirection URI — Après qu’un développeur a terminé le flux d’autorisation OAuth, il est redirigé vers Document360. Ajoutez l’URI de redirection de Document360 à la liste des URI de redirection autorisées de votre fournisseur OAuth :
https://your-apidocs-domain.com/oauth
Remplacez your-apidocs-domain.com par le domaine sur lequel la documentation de votre API Document360 est publiée.
Renouvellement silencieux — Document360 actualise automatiquement le jeton d’accès OAuth en arrière-plan pendant qu’un développeur utilise activement Try It !. Cela empêche la session d’expirer en plein usage. Aucune configuration n’est requise de votre côté car cela est géré automatiquement par Document360.
Exemple de définition de la spécification (Flux de code d’autorisation)
components:
securitySchemes:
oauth2Auth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.yourdomain.com/oauth/authorize
tokenUrl: https://auth.yourdomain.com/oauth/token
scopes:
read: Read access
write: Write access
OpenID Connect
OpenID Connect étend OAuth2 en ajoutant la vérification de l’identité utilisateur. Il est configuré de manière similaire à OAuth2 et a les mêmes exigences d’URI de redirection et de renouvellement silencieux.
Dans votre spécification OpenAPI :
components:
securitySchemes:
openIdConnect:
type: openIdConnect
openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration
La même exigence d’URI de redirection s’applique :
https://your-apidocs-domain.com/oauth
Application de plusieurs schémas de sécurité à un seul point d’accès
Si un point d’accès nécessite plusieurs méthodes d’authentification simultanément, définissez-les ensemble sous security le niveau de l’opération :
/secure-endpoint:
get:
security:
- BearerAuth: []
ApiKeyAuth: []
Cela nécessite à la fois un jeton porteur et une clé API fournis avant que la requête puisse être envoyée. Try It ! prend en charge plusieurs schémas de sécurité en une seule session.
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.
- Réponses dynamiques basées sur les instances – Document360 suit la spécification OpenAPI, qui définit une structure statique cohérente pour les objets requête et réponse. Si votre API renvoie des réponses différentes pour le même endpoint selon les environnements ou instances, Try It ! ne reflétera que ce qui est défini dans la spécification.
FAQ
Pourquoi l’URL Try It ! inclut-elle tryit.document360.io ?
C’est un comportement attendu. Le tryit.document360.io sous-domaine est utilisé en interne pour acheminer et traiter les requêtes de test de l’API. Cela n’affecte pas la fonctionnalité – les requêtes renvoient toujours les bons résultats de votre API.
Puis-je tester des points de terminaison qui nécessitent plus d’une méthode d’authentification ?
Oui. Try It ! prend en charge plusieurs systèmes de sécurité simultanément. Les développeurs peuvent configurer et envoyer des identifiants pour plusieurs schémas en une seule requête.
Un agent IA peut-il basculer entre MCP et l’API standard au sein du même flux de travail ?
Oui. Un seul flux de travail peut utiliser MCP pour les étapes de raisonnement et d’action — recherche, lecture, écriture, et appel direct à l’API standard pour des opérations hors du champ d’action de MCP. Les deux interfaces ne sont pas mutuellement exclusives ; Ils accèdent à la même base de connaissances sous-jacente.