Ce guide vous guide dans la publication de votre première référence API dans Document360, depuis le téléchargement de votre fichier spec jusqu’à un portail développeur interactif et en direct.
À la fin de cet article, vous aurez :
- Une référence API générée à partir de votre spécification OpenAPI
- Vos endpoints sont visibles et consultables par les développeurs
- La console interactive Try It ! prête pour les tests d’API en direct
La documentation API est disponible sur tous les forfaits payants. Chaque forfait payant comprend un espace de travail API. Des espaces de travail supplémentaires peuvent être achetés en extensions.
Prérequis
Avant de commencer, assurez-vous d’avoir :
- Un compte Document360 sur un forfait professionnel, professionnel ou entreprise.
- Un fichier de spécification API dans l’un de ces formats : OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1, ou Postman Collection. Les types de fichiers acceptés sont JSON, YAML ou YML.
- Accès au portail de la base de connaissances avec les autorisations de création de contenu.
Si vous n’avez pas encore de fichier de spécifications, vous pouvez toujours suivre ce guide en utilisant l’exemple de fichier API de la boutique animale fourni par Document360. On vous invitera à l’utiliser pendant la configuration.
Naviguez vers l’espace de travail de documentation de l’API
- Connectez-vous à Document360 et ouvrez votre projet dans le portail de la base de connaissances.
- Dans la barre de navigation de gauche, cliquez sur la documentation
{ }de l’API. Cela ouvre l’espace de travail dédié à l’API, séparé de votre base de connaissances standard. - Dans la barre de navigation du haut, cliquez sur le menu déroulant Créer et sélectionnez Nouvelle API. Cela ouvre la fenêtre de référence de la nouvelle API.
Vous pouvez créer un maximum de 3 références API dans chaque espace de travail API.
Choisissez comment importer votre spécification
Document360 prend en charge deux façons d’importer votre fichier de spécifications : le téléchargement de fichiers et l’importation d’URL. Le flux CI/CD n’est pas une méthode d’importation distincte ; C’est un moyen d’automatiser l’une ou l’autre de ces deux méthodes afin que votre documentation se mette à jour automatiquement à chaque changement de spécification.
| Méthode | Quand l’utiliser | Comment ça fonctionne |
|---|---|---|
| Téléchargement de fichier | Vous avez le fichier de spécifications localement sous forme JSON, YAML ou YML. | Téléchargez le fichier directement. C’est idéal pour commencer rapidement ou pour des mises à jour peu fréquentes. |
| Importation d’URL | Votre spec est hébergée sur une URL publique ou interne stable. | Pointez Document360 vers l’URL. Vous pouvez resynchroniser manuellement depuis la même URL chaque fois que la spécification change. |
| Flux CI/CD | Vous voulez que la documentation se mette à jour automatiquement à chaque changement de spécification. | Automatise l’upload des fichiers ou l’importation d’URL via la ligne de commande d360 dans votre pipeline. Ça demande Node.js. |
Téléchargez votre cahier des charges
Téléverser un fichier
- Dans la fenêtre de référence de la nouvelle API, sélectionnez l’option Télécharger la définition de l’API .
- Cliquez sur Télécharger depuis mon appareil ou glisser-déposer votre fichier. Formats pris en charge : JSON, YAML, YML.
- Document360 analyse le fichier et génère automatiquement la référence API. Si des avertissements sont détectés, une section Alertes et Avertissements apparaît — élargissez-la pour les examiner. Vous pouvez consulter tous les détails plus tard dans la section Journaux.
- Cliquez sur Nouvelle référence API pour continuer.
Importation à partir d’une URL
- Dans la fenêtre de référence de la nouvelle API, sélectionnez l’option Créer à partir de l’URL et cliquez sur Suivant.
- Entrez l’URL pointant vers votre fichier de spécification OpenAPI dans le champ URL.
- Document360 récupère et traite la spécification. Si des avertissements sont détectés, ils seront disponibles dans la section Journaux après l’importation.
- Cliquez sur Ajouter une référence API pour continuer.
Utiliser le flux CI/CD
Cette option nécessite Node.js installation sur votre système.
- Dans la fenêtre de référence de la nouvelle API, sélectionnez l’option CI/CD Flow .
- Copiez la commande CLI complète affichée dans la fenêtre.
- Dans la commande copiée, remplacez la
--pathvaleur par le chemin complet vers votre fichier de spécification local ou une URL valide pointant vers celui-ci. Par exemple :
--path=/Users/yourname/projects/api/openapi.yaml
Ou une URL :
--path=https://example.com/api/openapi.yaml
- Collez la commande mise à jour dans votre terminal et appuyez sur Entrée. Document360 télécharge votre spécification et génère la documentation de l’API.
La première ligne de la commande CLI (npm install d360 -g) installe l’outil CLI Document360. Tu n’as besoin de le faire qu’une seule fois. Si elle est déjà installée, vous pouvez éviter cette ligne.
Si vous régénérez votre clé API, vous devez mettre à jour la --apiKey valeur dans votre commande CLI avant de la relancer. L’ancienne clé ne sera plus valable.
Pas de fichier de spec ? Utilisez l’API de l’exemple de la boutique animale
Si vous n’avez pas de fichier de spécifications prêt, sélectionnez Essayer un fichier API de la boutique d’animaux d’exemple lorsque vous le demandez. Document360 créera automatiquement une référence API d’exemple en mode brouillon. Vous pouvez l’explorer puis le remplacer par votre propre spec plus tard.
Consultez les alertes et avertissements
Après avoir téléchargé votre spécification, Document360 vous montre un résumé du nombre de catégories et d’articles créés, ainsi que toute alerte ou avertissement détecté dans votre fichier.
- Les alertes et avertissements signifient que la spécification a été importée, mais certains éléments peuvent ne pas s’afficher comme prévu. Vous pouvez consulter tous les détails dans la section Journaux : allez dans votre référence API, cliquez sur l’icône Plus
(⋯), puis sélectionnez Journaux. - Les erreurs signifient que l’importation a échoué. La cause la plus fréquente est un format de fichier non pris en charge ou une URL invalide. Remplacez le fichier ou corrigez l’URL et réessayez.
Publiez votre référence API
Après que votre spotter ait été traité avec succès :
- Une fenêtre de confirmation affiche le nombre de catégories et d’articles créés. Cliquez sur Publier pour rendre la référence API en ligne.
- Si vous souhaitez revoir le contenu avant de publier, cliquez sur Fermer. Votre référence API est sauvegardée en mode brouillon et visible dans le volet Catégories & Articles.
Le mode brouillon est utile si vous souhaitez ajouter du contenu personnalisé à chaque article avant de les rendre publics. Tout contenu personnalisé que vous ajoutez sera conservé lorsque vous régénérerez ou resynchroniserez votre documentation.
Configurez l’authentification pour Try It !
La console Try It ! permet aux développeurs de tester vos points de terminaison API directement depuis la documentation. Pour que cela fonctionne correctement, la méthode d’authentification doit être définie dans votre spécification et configurée dans Document360.
Document360 prend en charge les méthodes d’authentification suivantes :
| 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. |
La console Try It ! prend en charge simultanément plusieurs schémas de sécurité, permettant de tester les points d’accès nécessitant des méthodes d’authentification combinées.
OAuth2 et OpenID Connect : configuration supplémentaire
Lors de l’utilisation d’OAuth2 ou OpenID Connect, deux paramètres sont nécessaires :
- Rediriger l’URI — Réglez-le dans votre fournisseur OAuth à
domain/oauth. Par exemple :https://apidocs.yourdomain.com/oauth. - Renouvellement silencieux — Document360 actualise automatiquement le jeton d’autorisation en arrière-plan lors des sessions actives Essayez-le !, afin que les utilisateurs n’aient pas besoin de se réauthentifier manuellement.
Si le bouton Essayer ! n’est pas visible sur votre site de base de connaissances, vérifiez que la variable serveur et l’URL du serveur sont correctement définies dans votre fichier de spécification API. Sans ceux-ci, la fonction Essaie ! ne fonctionnera pas.
Définir l’accès des lecteurs et la confidentialité
Contrôlez qui peut voir votre référence API publiée en configurant les paramètres d’accès au lecteur.
| Cadre | Ce que cela signifie |
|---|---|
| Privé | Seuls les comptes d’équipe peuvent consulter la référence de l’API. À utiliser pour des API internes ou réservées aux partenaires. |
| Public | N’importe qui peut accéder à la référence API sans authentification. |
| Mixte | Certaines sections sont publiques, d’autres sont limitées aux comptes d’équipe. |
Pour configurer l’accès du lecteur, naviguez dans Paramètres > Utilisateurs et Permissions > Accès au lecteur dans le portail de la base de connaissances, et localisez votre espace de travail de documentation API.
Consulter /apidocs avant la publication de tout article endpoint affichera une erreur 404 — il n’y a pas encore de contenu à afficher. Cela s’applique également si vous avez ajouté un lien /apidocs de navigation sur votre site de base de connaissances. Publiez au moins un article de point final avant de rendre votre référence API accessible aux lecteurs.