Prise en main de la documentation de l’API

Plans prenant en charge la documentation de l’API

La fonctionnalité de documentation API de Document360 fournit une solution complète pour la création et la gestion des références d’API. Cette fonctionnalité vous permet de générer une documentation d’API de haute qualité qui aide les utilisateurs à comprendre et à utiliser efficacement vos API. Vous pouvez générer cette documentation en téléchargeant le fichier de spécification d’API à partir d’une URL, d’un fichier JSON/YAML/YML ou en l’intégrant à un flux CI/CD.

De plus, la fonctionnalité Essayez-le ! de Document360 vous permet de tester les points de terminaison de l’API directement sur le Knowledge base site. La console interactive du site de la base de connaissances permet aux développeurs de saisir les paramètres nécessaires et d’exécuter des appels d’API, en obtenant des réponses en temps réel. Cette fonctionnalité est utile pour résoudre les problèmes et comprendre le comportement d’une API sans quitter la documentation ou écrire du code.

Intégration de la documentation API

Lors de l’inscription à Document360, les utilisateurs choisissent leur cas d’utilisation principal à l’étape 1 du processus d’intégration. Pour les utilisateurs qui souhaitent créer de la documentation API, Document360 offre une expérience d’intégration simplifiée. Si vous sélectionnez la documentation de l’API comme cas d’utilisation, vous serez redirigé vers le flux de configuration de l’API, où vous pouvez créer des références d’API à l’aide des options disponibles.

À l’étape 2 du flux d’intégration, vous aurez trois options pour créer une référence d’API :

• Charger le fichier API : prend en charge les fichiers JSON/YAML/YML (collections OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 et Postman).

• Créer à partir de l’URL : récupère automatiquement la spécification de l’API à partir de l’URL hébergée.

• Essayez un exemple de fichier API d’animalerie : si vous n’avez pas de fichier API prêt, vous pouvez utiliser le fichier d’exemple (API d’animalerie) proposé par Document360 pour remplir votre espace de travail.

Chargement d’un fichier de définition d’API

Pour créer une référence d’API à partir d’un fichier de définition d’API, sélectionnez la case d’option Télécharger le fichier API. Ensuite, cliquez sur Télécharger depuis mon appareil ou faites glisser et déposez votre fichier de spécification API depuis votre appareil.

NOTE

Les formats de fichier pris en charge pour le fichier de définition d’API sont JSON, YAML ou YML.

Le système analysera le fichier et générera automatiquement la référence de l’API.

• Si yalertes/avertissements sont détectés dans le fichier téléchargé, une vue d’ensemble de haut niveau s’affiche lors de l’intégration. Vous pouvez afficher des détails détaillés dans le portail de la base de connaissances dans la section des journaux sous Plus d’options dans les références d’API.

• Si une erreur est détectée dans le fichier téléchargé (par exemple, - Format de fichier non pris en charge), remplacez le fichier téléchargé par un autre fichier.

Saisie d’une URL de documentation API

Pour créer une référence d’API à partir d’une URL de documentation d’API, sélectionnez la case d’option Créer à partir d’une URL . Ensuite, entrez l’URL de votre fichier OpenAPI dans le champ URL de votre définition d’API . Document360 récupérera et traitera la structure de l’API. Semblable aux téléchargements de fichiers,

• Si des alertes/avertissements sont détectés, vous pouvez les afficher dans le portail de la base de connaissances dans la section des journaux sous Plus d’options dans les références d’API.

• Si une erreur est détectée (par exemple, URL non valide), entrez l’URL valide pour votre fichier OpenAPI.

Ignorer la configuration de l’API

Si vous choisissez l’option Essayer le fichier API de l’animalerie d’exemple ,

• Document360 créera automatiquement un exemple de référence d’API (API Pet store).

• Celui-ci sera disponible en mode brouillon. Vous pouvez examiner les points de terminaison avant de les publier ou télécharger votre fichier de spécification et le publier ultérieurement.

Personnalisez votre base de connaissances

À l’étape 3, vous pouvez entrer l’URL de votre site Web préféré. Si vous souhaitez sauter cette étape, le domaine sera par défaut celui lié à votre e-mail d’enregistrement.

Directives de la marque

À l’étape 4, le nom de votre projet, la langue par défaut, le logo de votre marque et les couleurs de la marque sont automatiquement définis en fonction de l’URL que vous avez fournie. Cependant, vous pouvez modifier ces champs si nécessaire. Les paramètres de langue de votre navigateur déterminent la langue par défaut. L’anglais sera sélectionné par défaut si d’autres langues ne prennent pas en charge la langue de votre navigateur.

NOTE

• Si vous choisissez l’espagnol ou le portugais brésilien comme langue par défaut, la langue du portail sera définie sur l’espagnol ou le portugais brésilien. Sinon, l’anglais sera la langue par défaut.

• Le logo de marque et les couleurs primaires/secondaires sont extraits de votre site web. Si vous choisissez d’ignorer cette étape, le nom du projet sera dérivé de votre e-mail d’inscription, et le logo et les couleurs par défaut de Document360 seront appliqués.

Définir la confidentialité de la documentation

À l’étape 5, vous pouvez choisir les paramètres de confidentialité souhaités pour votre site :

• Privé : limitez l’accès à la base de connaissances afin que seuls les comptes d’équipe puissent afficher et interagir avec le contenu, en le gardant sécurisé et interne.

• Public : Rendre la base de connaissances accessible à tous, y compris aux utilisateurs externes, en permettant un accès libre à tous les contenus.

• Mixte : combinez l’accès privé et public en permettant à certaines sections de la base de connaissances d’être visibles au public, tout en limitant les autres sections aux seuls comptes d’équipe.

Enfin, cliquez sur Suivant pour terminer votre processus d’intégration de l’API.

Vous serez redirigé vers l’espace de travail de documentation de l’API, où :

• Vous verrez la référence de l’API de la spécification d’API que vous avez fournie lors de l’intégration.

• Si vous n’avez pas fourni de spécification d’API, un exemple de référence d’API (API Pet store) sera disponible en mode brouillon.  

Techniques d’autorisation

Lorsque vous interagissez avec une API, il est important de s’assurer que seuls les utilisateurs autorisés peuvent accéder à certaines données ou effectuer des actions spécifiques. Cela se fait à l’aide de techniques d’autorisation, qui contrôlent l’accès et les autorisations. Document360 prend en charge différentes méthodes d’autorisation pour sécuriser votre API, notamment :

• Authentification de base : nécessite un nom d’utilisateur et un mot de passe transmis dans la demande.

• Jeton porteur : s’authentifie avec un jeton généré après la connexion.

• Clé API : utilise une clé unique, transmise dans les en-têtes de la demande, pour l’authentification.

• OAuth2 : sécurise les API par le biais de divers flux, tels que le code d’autorisation, la PKCE, les informations d’identification du client et les flux implicites.

• OpenID Connect : étend OAuth2 en ajoutant la vérification de l’identité de l’utilisateur.

Considérations relatives aux autorisations (OAuth2 et OpenID)

Lorsque vous utilisez des API qui utilisent OAuth2 ou OpenID pour l’autorisation, certains paramètres sont essentiels au bon fonctionnement.

• URI de redirection : il s’agit de l’URL vers laquelle l’utilisateur sera redirigé après avoir terminé un flux d’autorisation. Assurez-vous de définir l’URI au format : domain/oauth. Par exemple : https://apidocs.document360.com/oauth.

• Renouvellement silencieux : le renouvellement silencieux actualise automatiquement le jeton d’autorisation en arrière-plan, de sorte que les utilisateurs n’ont pas à se réauthentifier pendant leur session. Cela permet de garder leur session active sans interruption. Pour éviter que l’autorisation n’expire pendant les sessions où les utilisateurs interagissent avec la fonctionnalité Essayez-le ! , Document360 renouvelle automatiquement le jeton d’actualisation en arrière-plan. Cela garantit que les utilisateurs n’auront pas besoin de se réauthentifier manuellement.

Achat

Vous aurez accès à 1 espace de travail API dans le cadre de tous les plans payants de Document360 (Professional, Business et Enterprise). Si vous souhaitez acheter des espaces de travail API supplémentaires,

1. Accédez à Settings() > portail de la base de connaissances > Facturation > Mon forfait.

2. Cliquez sur Acheter un module complémentaire.

3. Ajoutez le nombre souhaité d’espaces de travail de documentation API. Vérifiez le coût de l’add-on et le montant dû.

4. Cliquez sur Confirmer le paiement pour procéder au paiement.

Dépannage

Problèmes d’accès à l’API

Erreur : Erreur 400 – L’accès à l’API est désactivé. Veuillez contacter votre administrateur de projet.

Cette erreur se produit lorsque l’accès à l’API publique est désactivé dans les paramètres du projet.

Étapes à résoudre :

1. Accédez à Settings() > fonctionnalités AI > Eddy AI dans le portail de la base de connaissances.

2. Dans la section Suite de recherche IA , assurez-vous que la case API publique est cochée.

   

3. Si le problème persiste après avoir suivi ces étapes, veuillez contacter l’équipe d’assistance Document360 pour obtenir de l’aide supplémentaire : Contacter l’assistance Document360

Vidéos connexes

Découvrez notre documentation API moderne dans Document360 comme jamais auparavant

Testez les points de terminaison de l’API directement à partir de la documentation avec la fonction d’essai

Informations complémentaires

Présentation de la documentation API : Améliorez votre expérience API - Cliquez pour lire