Gestion de la documentation API

La fonctionnalité de documentation API dans Document360 facilite la création de documentation claire et interactive en téléchargeant vos fichiers de spécifications API. Ce processus construit automatiquement une documentation détaillée couvrant tout, des points d'accès API aux méthodes et réponses, aidant ainsi les développeurs à comprendre et à utiliser votre API de manière plus efficace.  

Génération de la documentation de l'API

Il existe trois méthodes pour générer la documentation API dans Document360 :

• À partir d'une URL

• À partir d'un fichier JSON/YAML/YML

• Avec un flux CI/CD

NOTE

Document360 prend en compte OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 et les spécifications de Postman.

Générer la documentation API à partir d'un fichier de spécification API

Pour générer des références API à partir d'un fichier de spécification API (JSON/YAML/YML),

1. Naviguez vers le projet souhaité dans le portail de la base de connaissances.

2. Sélectionnez la documentation API ({ }) dans la barre de navigation de gauche.

3. Cliquez sur le menu déroulant Créer dans la barre de navigation supérieure et sélectionnez Nouvelle API. Cela affichera la fenêtre de référence de la nouvelle API .

4. Sélectionnez le bouton Définition d'API de téléversement dans la fenêtre de référence de la nouvelle API .

5. Cliquez sur Télécharger depuis mon appareil ou Choisir entre Drive pour sélectionner le fichier depuis votre appareil ou Document360 Drive, respectivement. Vous pouvez aussi glisser-déposer votre fichier directement dans la fenêtre de référence de la nouvelle API.

NOTE

Le processus d'importation de la documentation API prend en charge les sous-catégories de second niveau utilisant le > symbole dans les balises OpenAPI (par exemple, Pets > Details). Cela permet une organisation plus propre et imbriquée des points de terminaison, préserve la structure lors de la resynchronisation, et assure un affichage et une navigation appropriés dans le panneau gauche de la référence API.

Si votre fichier téléchargé contient des alertes ou avertissements associés, vous pouvez les consulter en agrandissant les menus déroulants Alertes et Avertissements , qui apparaissent dans la fenêtre de référence de la nouvelle API.

6. Cliquez sur Nouvelle référence API pour accéder à la fenêtre de confirmation de publication . Vous verrez un message de réussite dans la fenêtre, ainsi que le nombre de catégories et d'articles créés.

7. Cliquez sur Publier pour générer la documentation de votre API.

NOTE

Pour consulter votre documentation avant publication, cliquez sur Fermer pour revenir à l'écran de la Documentation. Votre brouillon sera visible dans le volet Catégories & Articles .

Générer la documentation API à partir d'une URL

Pour télécharger le fichier de spécification API en tant qu'URL vers Document360,

1. Naviguez vers le projet souhaité dans le portail de la base de connaissances.

2. Sélectionnez la documentation API ({ }) dans la barre de navigation de gauche.

3. Cliquez sur le menu déroulant Créer dans la barre de navigation supérieure et sélectionnez Nouvelle API ou cliquez sur le bouton Nouvelle API en haut à droite. Cela affichera le panneau de référence de la nouvelle API .

4. Dans l'écran Choisir la source , sélectionnez le bouton Créer à partir de l'URL , puis cliquez sur Suivant.

5. Dans l'écran des paramètres source , saisissez l'URL de votre fichier de spécification API dans le champ URL .

6. Cliquez sur Ajouter une référence API pour accéder à l'écran Terminer .

7. Sur l' écran Terminer , vous pourrez voir le nombre de catégories et d'articles créés pour votre fichier de spécification API.

8. Cliquez sur Publier pour générer la documentation de votre API.

Générer une documentation API avec un flux CI/CD

Avant de télécharger un fichier de spécification API avec un flux CI/CD, assurez-vous que la dernière version de Node.js est installée sur votre système. Si vous ne connaissez pas Node.js, consultez ce guide pour les instructions d'installation.

Pour téléverser le fichier de spécification API avec un flux CI/CD,

1. Naviguez vers le projet souhaité dans le portail de la base de connaissances.

2. Sélectionnez la documentation API ({ }) dans la barre de navigation de gauche.

3. Cliquez sur le menu déroulant Créer dans la barre de navigation supérieure et sélectionnez Nouvelle API. Cela affichera la fenêtre de référence de la nouvelle API .

4. Dans l'écran Choisir la source , sélectionnez le bouton radio CI/CD Flow .

5. Copiez la commande CLI complète affichée depuis la fenêtre de référence de la nouvelle API .

6. Dans la commande copiée, mettez à jour la --path valeur avec :

   • Le chemin complet vers votre fichier local JSON/YAML/YML s. Par exemple,

     --path=/Users/yourname/projects/api/openapi.yaml

   • Une URL valide pointant vers votre fichier de spécification API. Par exemple,

     --path=https://example.com/api/openapi.yaml

7. Collez la commande mise à jour dans votre terminal et appuyez sur Entrée.  

8. Votre fichier de spécifications API sera téléchargé, et la documentation API seragénérée.

NOTE

• La première ligne (npm install d360 -g) installe l'outil CLI Document360. Il suffit de le lancer la première fois. Si c'est déjà installé, tu peux éviter cette ligne.

• Si vous régénérez la clé API en cliquant sur l'icône () dans l'interface, vous devez mettre à jour la --apiKey valeur dans votre commande CLI avant de la relancer. L'ancienne clé ne sera plus valable.

Gestion des webhooks (événements)

Lorsque votre spécification OpenAPI 3.1 inclut des webhooks, Document360 les importe et affiche une icône d'événement à côté de chaque webhook. La page affiche le schéma de la charge utile et l'exemple. Si la spécification n'inclut pas d'exemple, un exemple par défaut et une charge utile d'échantillon sont affichés. Essayez, ce n'est pas disponible pour les webhooks. Les webhooks sont inclus dans les opérations de resynchronisation, et votre contenu personnalisé est conservé après régénération.

Documentation de régénération de l'API

Si vous apportez des modifications à votre API, comme l'ajout de nouveaux points de terminaison, vous n'avez pas besoin de mettre à jour manuellement votre documentation API dans Document360. Vous pouvez régénérer la documentation de votre API, et toute modification apportée à votre API sera automatiquement reflétée dans la documentation mise à jour.

NOTE

Tout contenu personnalisé que vous ajoutez à votre documentation API sera conservé lorsque vous régénérerez votre documentation.

Régénérer la documentation de l'API à partir de l'URL

1. Naviguez vers le projet souhaité dans le portail de la base de connaissances.

2. Sélectionnez la documentation API ({ }) dans la barre de navigation de gauche.

3. Cliquez sur références API dans le volet de navigation de gauche.

4. Cliquez sur l' icône More () à côté de la référence API souhaitée pour laquelle vous souhaitez régénérer la documentation de l'API.

   1. Pour régénérer la documentation de l'API à partir de l'URL existante :

      • Cliquez sur Resynchroniser.

      • La documentation API sera régénérée selon le dernier fichier de spécification API.

   

   1. Pour régénérer la documentation de l'API avec une nouvelle URL :

      • Cliquez sur modifier.

      • Saisissez la nouvelle URL dans le champ URL .

      • Cliquez sur Mettre à jour.

      • La documentation de l'API sera régénérée selon le fichier de spécification API à la nouvelle URL.

Régénérer la documentation API à partir d'un fichier de spécifications API

1. Naviguez vers le projet souhaité dans le portail de la base de connaissances.

2. Sélectionnez la documentation API ({ }) dans la barre de navigation de gauche.

3. Cliquez sur références API dans le volet de navigation de gauche.

4. Cliquez sur l' More () à côté de la référence API souhaitée pour laquelle vous souhaitez régénérer la documentation de l'API.

5. Edit.

6. Téléchargez le dernier fichier de spécification API au format JSON/YAML/YML.

7. Cliquez sur Mettre à jour. La documentation API sera régénérée selon le dernier fichier de spécification API.

Documentation de régénération API intégrée au flux CI/CD

Vous pouvez resynchroniser la référence API dans vos pipelines CI/CD avec l'aide de vos packages d360 npm. D360 est l'outil en ligne de commande qui vous aide à configurer des flux de travail synchronisant vos documents API avec Document360.

Vous pouvez également effectuer la resynchronisation manuellement en utilisant la commande ci-dessous.

d360 apidocs:resync 
                    --apiKey=API_key_value
                    --userId=user_id_value
                    --apiReferenceId=API_reference_value
                    --path=Spec_file_path

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 supprimés définitivement, ainsi que tout contenu personnalisé ajouté à ces pages de points.

Pour mettre à jour votre fichier de spécifications API :

1. Téléchargez le fichier de spécification de l'API mis à jour dans la fenêtre de référence Modifier l'API .

2. 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.

3. Sélectionnez la case Confirmer pour continuer afin de confirmer la suppression.

4. 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.

 NOTE

Si vous utilisez le point de terminaison de l'API de resynchronisation de façon programmatique, envoyez ForceImport = false votre requête pour prévisualiser la liste des points de terminaison qui seront supprimés sans procéder à la suppression. Envoyez ForceImport = true pour confirmer et procédez.

Télécharger la source de l'API

NOTE

Pour télécharger les fichiers API, assurez-vous que le bouton Afficher la source du téléchargement de l'API dans les paramètres du portail de la Knowledge base est activé .

Liens utiles