Cet article couvre tout ce dont vous avez besoin pour gérer vos références API dans Document360. Créer de nouvelles références, les garder synchronisées avec votre spécification, et utiliser les actions disponibles pour voir, modifier, publier et organiser votre documentation API.
Liste des références API
La liste des références API vous donne une vue centrale de toutes les références API configurées dans votre espace de travail. Pour y accéder, naviguez dans la documentation API ({ }) dans la barre de navigation de gauche et cliquez sur Références API dans le panneau de navigation de gauche.
À partir de là, vous pouvez voir le nom, le type et la date de dernière mise à jour pour chaque référence. Vous pouvez également créer une nouvelle référence API en cliquant sur Nouvelle API en haut à droite.
Créer une nouvelle référence API
Pour créer une nouvelle référence API, cliquez sur le menu déroulant Créer dans la barre de navigation supérieure et sélectionnez Nouvelle API. Cela ouvre la fenêtre de référence de la nouvelle API où vous avez quatre options :
- Définition de l’API de téléversement - Téléchargez un fichier de spécification JSON, YAML ou YML directement depuis votre appareil ou depuis Document360 Drive.
- Créer à partir d’une URL - Récupérez automatiquement votre spécification depuis une URL hébergée.
- Flux CI/CD - Intégrez votre pipeline pour mettre à jour automatiquement la documentation à chaque changement de spécification. Ça demande Node.js.
- Essayez un exemple de fichier API de la boutique animalerie - Utilisez le fichier spec d’exemple de Document360 pour explorer l’espace de travail avant de télécharger le vôtre.
Document360 prend en compte OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 et les spécifications de Postman. Dans chaque espace de travail API, vous pouvez créer un maximum de 3 références API.
Définition de l’API de téléversement
- Sélectionnez le bouton de définition de l’API Upload .
- Cliquez sur Télécharger depuis mon appareil pour télécharger depuis votre stockage local, ou Choisir parmi Drive pour sélectionner un fichier depuis Document360 Drive. Vous pouvez aussi glisser-déposer votre fichier directement dans la fenêtre.
- Document360 analyse le fichier et génère la référence API. Si des avertissements sont détectés, élargissez la section Alertes et Avertissements pour les examiner.
- Cliquez sur Nouvelle référence API pour accéder à la fenêtre de confirmation de publication.
Créer à partir de l’URL
- Sélectionnez le bouton Créer à partir de l’URL et cliquez sur Suivant.
- Saisissez l’URL pointant vers votre fichier de spécification OpenAPI.
- Cliquez sur Nouvelle référence API. Document360 récupère et traite la spécification.
Flux CI/CD
Le flux CI/CD vous permet de garder automatiquement votre documentation API synchronisée avec votre spécification. Au lieu de télécharger manuellement une nouvelle spécification à chaque changement d’API, vous intégrez la CLI Document360 dans votre pipeline afin que la documentation se mette à jour automatiquement à chaque changement de spécification.
Pour les instructions complètes de configuration, voir l’article sur l’intégration CI/CD .
Actions de référence API
Une fois une référence API créée, cliquez sur l’icône More (⋯) à côté dans la liste des références API pour accéder aux actions suivantes :
| Action | Ce que ça fait |
|---|---|
| Édit | Mettez à jour le fichier de spécifications ou l’URL à partir de laquelle la référence a été créée. |
| Resynchronisation | Régénérez la documentation à partir de la dernière version de la spécification à l’URL existante. |
| Voir la définition de l’API | Prévisualisez le fichier brut de spécification de l’API. |
| Télécharger la source originale de l’API | Téléchargez la version actuelle du fichier de spécifications dans votre stockage local. |
| Publier | Publiez tous les articles brouillons dans la référence API du site de la base de connaissances. |
| Supprimer | Supprimez définitivement la référence API et tout son contenu généré. |
| Voir les journaux | Consultez les alertes, avertissements et erreurs liés à la dernière importation ou resynchronisation. |
Pour permettre aux lecteurs de télécharger le fichier source de l’API depuis le site de la Base de connaissances, assurez-vous que le bouton Afficher le code source de l’API est activé dans les paramètres du portail de la Base de connaissances.
Garder votre documentation synchronisée
Lorsque votre API change - de nouveaux points de terminaison ajoutés, des paramètres mis à jour, des réponses modifiées, mais vous n’avez pas besoin de mettre à jour votre documentation manuellement. Régénérer la référence de votre API récupère automatiquement toutes les modifications de votre spécification.
Tout contenu personnalisé ajouté à chaque article endpoint est conservé lorsque vous régénérez votre documentation. Seul le contenu généré par la spécification est mis à jour.
Resynchronisation à partir d’une URL existante
- Dans la liste des références API, cliquez sur l’icône Plus (⋯) à côté de la référence que vous souhaitez mettre à jour.
- Cliquez sur Resynchroniser. La documentation se régénère à partir de la dernière version de la spécification à l’URL existante.
Mise à jour vers une nouvelle URL
- Cliquez sur l’icône Plus (⋯) à côté de la référence.
- Cliquez sur modifier.
- Saisissez la nouvelle URL dans le champ URL .
- Cliquez sur Mettre à jour.
Régénérer à partir d’un fichier de spécifications
- Cliquez sur l’icône Plus (⋯) à côté de la référence.
- Cliquez sur modifier.
- Téléchargez le dernier fichier de spécifications en format JSON, YAML ou YML.
- Cliquez sur Mettre à jour.
Resynchronisation via CI/CD
Si votre référence API a été configurée avec le flux CI/CD, la resynchronisation se fait automatiquement dans votre pipeline à chaque changement de spécification. Vous pouvez également déclencher une resynchronisation manuelle en utilisant la apidocs:resync commande :
d360 apidocs:resync \
--apiKey=YOUR_API_KEY \
--userId=YOUR_USER_ID \
--apiReferenceId=YOUR_API_REFERENCE_ID \
--path=PATH_TO_SPEC_FILE
Pour tous les détails sur la configuration et la gestion du flux CI/CD, voir l’article sur l’intégration CI/CD .
Resynchronisation automatique vs manuelle
| Méthode de création | Resynchronisation automatique | Resynchronisation manuelle |
|---|---|---|
| Téléchargement de fichier | Non disponible | Oui, via Modifier dans le portail |
| Importation d’URL | Non disponible | Oui, via la Resynchronisation ou l’Édition dans le portail |
| Flux CI/CD | Oui - ça fait partie de votre pipeline | Oui, exécute la commande CLI manuellement |
Si vous avez généré votre documentation API à partir d’une URL ou d’un fichier, elle ne se mettra pas à jour automatiquement. Pour que la documentation soit mise à jour automatique, intégrez avec le flux CI/CD.
Comprendre la suppression des terminaux lors de la resynchronisation
Lorsque vous mettez à jour votre fichier de spécification API, tous les points de terminaison qui ne sont plus présents dans la nouvelle spécification sont définitivement supprimés, ainsi que tout contenu personnalisé ajouté à ces pages de points.
Pour mettre à jour votre fichier de spécifications en toute sécurité :
- Téléchargez le fichier de spécifications mis à jour dans la fenêtre de référence Modifier l’API .
- Si des points de terminaison sont supprimés, un avertissement s’affiche. Cliquez sur Afficher les terminaux supprimés pour consulter la liste des points affectés.
- Sélectionnez la case Confirmer pour continuer afin de confirmer la suppression.
- Cliquez sur Mettre à jour pour continuer.
Les points de terminaison supprimés sont déplacés dans la corbeille de recyclage, où ils peuvent être prévisualisés jusqu’à 30 jours mais ne peuvent pas être restaurés.
Si vous utilisez l’API de resynchronisation de façon programmatique, envoyez ForceImport = false en prévisualisation la liste des points de terminaison qui seront supprimés sans continuer. Envoyez ForceImport = true pour confirmer et procédez.
Conservation de la documentation en version provisoire
Après avoir téléchargé ou resynchronisé une spécification, vous pouvez garder la documentation résultante en mode brouillon plutôt que de la publier immédiatement.
- Dans la fenêtre de confirmation de publication, cliquez sur Fermer au lieu de Publier. Tous les articles générés resteront en mode brouillon.
- Les articles brouillons sont visibles dans le volet Catégories & Articles du portail mais ne sont pas accessibles aux lecteurs sur le site de la base de connaissances.
- Vous pouvez revoir, éditer et ajouter du contenu personnalisé pour les rédiger avant de publier.
Catégories imbriquées
Document360 prend en charge jusqu’à trois niveaux de sous-catégories dans l’espace de travail de documentation API. Les catégories sont créées en fonction des définitions des tags dans votre fichier de spécifications.
Pour créer des catégories imbriquées, utilisez le > symbole dans vos balises OpenAPI :
tags:
- name: "Pets > Details"
Cela crée une Pets catégorie avec une Details sous-catégorie à l’intérieur. Cette structure est préservée lors de la resynchronisation.
Si votre spécialisation définit plus de trois niveaux de nesting, toutes les catégories au-delà du troisième niveau sont placées au troisième niveau.
Ordre des catégories
L’ordre dans lequel les catégories apparaissent dans votre documentation correspond à l’ordre des tags défini dans votre fichier de spécifications. Pour changer l’ordre des catégories, réorganisez le tags tableau dans votre spécification et resynchronisez.
Options de catégorie
En cliquant droitement sur une catégorie dans le volet Catégories & Articles, vous obtenez les options suivantes :
| Option | Ce que ça fait |
|---|---|
| Renom | Renommer la catégorie. |
| Article | Ajoutez un nouvel article ou un sous-article dans la catégorie. |
| Sous-catégorie | Ajoutez une sous-catégorie à l’intérieur de la catégorie. |
| Changement de type | Changez le type de catégorie. |
| Définir le dossier du disque | Mettez la catégorie en lien avec un dossier Document360 Drive. |
| Modifier la référence API | Mettez à jour le fichier de spécification ou l’URL pour la référence de l’API. |
| Télécharger la source originale de l’API | Téléchargez le fichier de spécifications actuel. |
| Publier | Publiez tous les articles brouillons dans cette catégorie. |
| Sécurité | Configurez qui peut accéder à la catégorie depuis le portail et le site de la base de connaissances. |
Vous pouvez déplacer des articles de terminaison entre sous-dossiers au sein du même dossier de référence API. Il n’est pas possible de déplacer un article endpoint d’un dossier de référence API vers un autre dossier de référence API.
FAQ
À quelle fréquence une référence API est-elle automatiquement resynchronisée ?
Les références API créées à partir d’une URL ou d’un fichier ne sont pas resynchronisées automatiquement. Ils doivent être mis à jour manuellement via le portail. Pour activer les mises à jour automatiques, intégrez avec le flux CI/CD.
Puis-je déplacer un article spécifique sur un endpoint API d’un dossier de référence API à un autre ?
Non. Vous pouvez déplacer les articles de terminaison entre des sous-dossiers au sein du même dossier de référence API, mais pas entre différents dossiers de référence API.
Un article de documentation API peut-il avoir la même URL qu’un article de base de connaissances ?
Non. Les articles de documentation API et les articles de la Knowledge Base ne peuvent pas partager la même URL. Cependant, ils peuvent exister sous le même sous-domaine.
Puis-je garder la documentation générée en mode brouillon ?
Oui. Après avoir téléchargé une spécification, cliquez sur Fermer au lieu de Publier dans la fenêtre de confirmation. Tous les articles générés seront sauvegardés en mode brouillon.
Combien de niveaux de catégories sont pris en charge ?
L’espace de travail de documentation API prend en charge jusqu’à trois niveaux de sous-catégories. Des niveaux supplémentaires sont regroupés au troisième niveau.
Puis-je créer des dossiers imbriqués automatiquement à partir du fichier de spécifications ?
Oui, en utilisant le > symbole dans les balises OpenAPI (par exemple Pets > Details). Cela crée une structure hiérarchique qui est préservée lors de la resynchronisation.
Les lecteurs peuvent-ils accéder au site de la base de connaissances pendant les interruptions du portail Document360 ?
Oui. Les appels GET de l’API Client s’exécutent indépendamment du portail Document360, permettant aux lecteurs de continuer à accéder au site pendant la maintenance programmée ou les interruptions du portail.