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écification API sera téléchargé, et la documentation API sera gé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

Télécharger la référence API

NOTE

Pour télécharger les fichiers API, assurez-vous que le bouton Afficher la référence de l'API dans les paramètres du portail de la Base de connaissances est activé.

Dépannage

URL serveur manquante ou incorrecte dans OpenAPI

 Erreur : Cette erreur survient lorsque l' URL du serveur manque ou est mal configurée dans la spécification OpenAPI. En conséquence, les utilisateurs de l'API ne savent pas où envoyer les requêtes API, et le bouton « Essayer » peut ne pas être disponible dans la documentation de l'API. La cause principale est généralement une section manquante ou incorrecte servers dans la spécification OpenAPI.

Étapes pour résoudre

Pour résoudre ce problème, assurez-vous que la spécification OpenAPI inclut la bonne URL serveur :

1. Définissez l'URL serveur dans la spécification OpenAPI :

   servers:
     - url: https://apihub.document360.io
       description: Main API hub

2. Pour les API basées sur la région, définissez plusieurs URL de serveur :

   servers:
     - url: https://apihub.document360.io
       description: Global API hub
     - url: https://apihub.us.document360.io
       description: US region API hub

3. Assurez-vous que tous les clients API (par exemple, Postman, cURL) utilisent la bonne URL serveur lors des requêtes.

NOTE

Les URL ci-dessus en sont des exemples. Veuillez vous référer à la configuration spécifique de votre API pour la bonne URL serveur.

Exemple :

Exemple YAML pour manque servers   Section :

paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    userId:
                      type: integer
                    userName:
                      type: string

Pour éviter ce problème, assurez-vous que le servers section est correctement définie dans la spécification OpenAPI afin d'éviter que les consommateurs d'API n'aient à construire manuellement les URL de requêtes API.

Erreur 401 non autorisée provenant d'une URL serveur incorrecte

Erreur : Cette erreur survient lorsque les requêtes API renvoient une réponse non autorisée 401 . Cela se produit généralement lorsqu'une URL serveur incorrecte est utilisée dans les requêtes API. Par exemple, utiliser https://apihub.document360.io à la place de https://apihub.us.document360.io provoque des échecs d'authentification.

Étapes à résoudre :

Pour résoudre ce problème, suivez ces étapes pour garantir une utilisation correcte des URL du serveur et une authentification appropriée :

1. Assurez-vous que les requêtes API utilisent le bon point de terminaison basé sur la région.

2. Confirmez que le bon identifiant client et le secret client sont utilisés.

Exemple de requête API correcte :

GET https://apihub.us.document360.io/v2/Articles/{article_id}/en?appendSASToken=true

NOTE

L'URL ci-dessus en est un exemple. Veuillez vous référer à la configuration spécifique de votre API pour la bonne URL serveur.

3. Assurez-vous que le jeton d'authentification est correctement inclus dans les en-têtes de requête.

URL serveur manquante dans la documentation de l'API

Erreur : Ce problème survient lorsque les consommateurs d'API ne savent pas quelle URL de base utiliser pour leurs requêtes. Cela se produit généralement lorsque la documentation ne précise pas clairement l'URL du serveur, même si elle peut être correctement configurée dans la spécification OpenAPI.

Étapes à résoudre :

Pour éviter toute confusion et s'assurer que les consommateurs de l'API connaissent la bonne URL de base :

1. Spécifiez explicitement l'URL de base dans la documentation de l'API.

Exemples :

Tableau comparatif : URL serveur présente vs. manquante

NOTE

Les URL ci-dessus en sont des exemples. Veuillez vous référer à la configuration spécifique de votre API pour la bonne URL serveur.

Pour éviter ce problème, assurez-vous que la documentation de l'API précise clairement l'URL du serveur afin d'éviter toute confusion.

Erreur 403 lors de l'utilisation de la fonction « Essayer » avec un fichier OAS

Erreur :

Après avoir téléchargé avec succès un fichier OAS, cliquer sur la fonction Essayer donne une erreur 403. Cette erreur survient lorsque le fichier OAS manque d'une définition du mécanisme de sécurité BearerAuth .

Étapes à résoudre :

Pour résoudre l'erreur 403, suivez ces étapes :

1. Vérifiez si la définition de sécurité BearerAuth est présente dans votre fichier OAS.

2. Si la définition BearerAuth manque, incluez la définition de sécurité BearerAuth dans le fichier OAS et retéléchargez-la.

3. Pendant le processus d'importation, vérifiez si des alertes liées à l' authentification par porteur sont déclenchées et adressez-les en conséquence.

Stylisation HTML incorrecte dans la réponse API

Lors de la récupération du contenu HTML d'un article via une API, la réponse est formatée en JSON, qui utilise l'échappement (\") pour gérer certains caractères en toute sécurité. Cette fuite modifie des caractères comme les guillemets, les barres oblique et les nouvelles lignes pour éviter les erreurs de transmission de données. Cependant, si les caractères échappés ne sont pas convertis en retour (non échappés), la structure HTML peut se détériorer, entraînant des problèmes de style lors du rendu.

Par exemple, un simple paragraphe HTML :

<p>This is a "sample" paragraph.</p>

Peut apparaître dans la réponse JSON comme suit :

"<p>This is a \"sample\" paragraph.</p>"

Les doubles guillemets échappés (\") garantissent que le JSON reste valide, mais si ce n'est pas échappé, le HTML pourrait ne pas s'afficher correctement.

Étapes pour résoudre

1. Récupérez le contenu HTML via l'API et inspectez la réponse.

2. Cherchez des personnages évadés dans la réponse JSON, tels que :

   • \" (guillemets doubles échappés)

   • \\ (coups de mâle échappés)

   • \n (nouvelle ligne)

   • \t (tab)

3. Dégagez le contenu JSON avant de le rendre officiellement. Cela restaurera la structure HTML originale.

4. Vérifiez le style après avoir détaché pour vous assurer que le contenu est correct.

5. Si le problème persiste, vérifiez si des modifications supplémentaires dans votre code modifient la réponse de l'API.

   

   Une fois correctement débarrassé, le HTML s'affichera comme prévu, évitant ainsi les écarts de style.

Les variables et extraits ne sont pas affichés dans la réponse API

Lors de la récupération du contenu d'un article via l'API, les variables et extraits peuvent apparaître non traités (par exemple, {{variable.UserName}} au lieu de valeurs réelles). Cela se produit généralement lorsque le "isForDisplay" paramètre n'est pas correctement réglé.

• Si "isForDisplay" = true, l'API retournera le contenu de l'article avec toutes les variables et extraits entièrement rendus. Cela signifie que les espaces réservés sont remplacés par des valeurs réelles, rendant le contenu adapté à l'affichage des utilisateurs finaux.

• Si "isForDisplay" = false (ou non) défini, la réponse API contiendra des variables et des extraits non traités, ce qui peut ne pas être utile pour l'affichage direct.

  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

Contenu de l'article dans la base de connaissances :

Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}.

Réponse API sans "isForDisplay":

"Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}."

Les variables restent non traitées, ce qui le rend inadapté à l'affichage direct.

Réponse API avec "isForDisplay"=true:

"Welcome, John! Here’s how to use Document360."

Étapes à résoudre :

1. Récupérez le contenu de l'article via une API et inspectez la réponse.

2. Vérifiez si des variables ou des extraits semblent non traités dans la réponse.

3. Assurez-vous que la requête API inclut le "isForDisplay" paramètre. En cas de manque, modifiez la requête pour inclure "isForDisplay": true.

4. Envoyez la requête API modifiée. Exemple de demande :

   {
     "articleId": "12345",
     "isForDisplay": true
   }

5. Vérifiez si la réponse de l'API affiche désormais les variables et extraits correctement rendus.

6. Si le problème persiste, assurez-vous que le système traitant la réponse API gère et affiche correctement le contenu rendu.

7. Lors de la mise à jour des articles via l'API, ne passez pas de contenu entièrement rendu afin d'éviter de remplacer les espaces réservés dynamiques par des valeurs statiques.

Le corps vide est indiqué dans la documentation de l'API en raison d'un type de schéma manquant

La documentation de l'API affiche un corps vide. La cause possible de cette erreur pourrait être que le schéma OpenAPI manque de l' “type": "object” attribut dans une ou plusieurs définitions d'objets.

Étapes à résoudre :

Assurez-vous que chaque définition d'objet dans votre spécification OpenAPI inclut “type": "object”. Cet attribut précise clairement que la structure définie est un objet, aidant à maintenir la clarté et la cohérence dans la documentation de votre API. Il permet aux outils de documentation de l'API de rendre avec précision les paramètres du corps des requêtes, les schémas de réponse et d'autres définitions d'objets, facilitant ainsi la compréhension et l'interaction de votre API pour les développeurs.

Problème lors de l'ajout d'une référence API

Erreur : impossible d'ajouter une référence API. Cette opération ne peut pas être menée à terme. Veuillez vous assurer d'avoir fourni un fichier de spécifications valide.

La cause possible pourrait être que le fichier de spécification téléchargé (YAML) soit mal formé et ne soit pas un YAML OpenAPI 3.0 valide. Cela se produit souvent lorsque le fichier est copié ou exporté depuis un éditeur de texte enrichi, ce qui introduit des problèmes de formatage.

Étapes à résoudre :

1. Validez votre fichier de spécifications : Ouvrez votre fichier YAML dans un outil comme Swagger Editor ou un éditeur de code pour vérifier les erreurs ou les problèmes de mise en forme.

2. Recherchez les caractères de mise en forme indésirables : vérifiez s'il y a des caractères comme \f0\fs24 ou des barres oblique \ qui ont pu être introduits lors d'un copier-coller depuis une source en texte riche. Celles-ci peuvent casser le format YAML.

3. Nettoyez le fichier : utilisez un texte brut ou un éditeur de code pour supprimer tout caractère de mise en forme spécial. Évitez d'utiliser des traitements de texte lors de l'édition ou de l'enregistrement de fichiers YAML.

4. Téléversez à nouveau le fichier : Après avoir nettoyé le fichier et vérifié qu'il s'agit d'un YAML OpenAPI 3.0 valide, essayez de le télécharger à nouveau.

Liens utiles