Gestion de la documentation de l’API

Plans à l’appui de la documentation API

La fonctionnalité de documentation API de Document360 facilite la création d’une documentation claire et interactive en téléchargeant vos fichiers de spécification API. Ce processus crée automatiquement une documentation détaillée qui couvre tout, des points de terminaison de l’API aux méthodes et réponses, aidant ainsi les développeurs à comprendre et à utiliser votre API plus efficacement.

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

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

• À partir d’une URL

• À partir d’un  fichier JSON/YAML

• Avec un flux CI/CD

NOTE

Document360 prend en charge les spécifications OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 et Postman API.

Génération de la documentation API à partir d’un fichier de spécification d’API

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

1. Accédez au projet souhaité dans le portail de la base de connaissances.

2. Sélectionnez Documentation de l’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. La fenêtre de référence Nouvelle API s’affiche.

4. Sélectionnez l’option Télécharger la définition de l’API dans la fenêtre Référence de la nouvelle API .

5. Cliquez sur Télécharger à partir de mon appareil ou sur Choisir dans le lecteur pour sélectionner le fichier sur votre appareil ou sur le lecteur Document360, respectivement. Vous pouvez également glisser-déposer votre fichier directement dans la fenêtre de référence Nouvelle API .

Si votre fichier téléchargé est associé à des alertes ou des avertissements, vous pouvez les afficher en développant les listes déroulantes Alertes et avertissements qui s’affichent dans la fenêtre de référence Nouvelle API.

6. Cliquez sur Nouvelle référence d’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 qui ont été créés.

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

NOTE

Pour consulter votre documentation avant de la publier, cliquez sur Fermer pour revenir à l’écran Documentation. Votre brouillon sera visible dans le volet Catégories et articles .

Génération de la documentation de l’API à partir d’une URL

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

1. Accédez au projet souhaité dans le portail de la base de connaissances.

2. Sélectionnez Documentation de l’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 dans le coin supérieur droit. Le panneau de référence Nouvelle API s’affiche.

4. Dans l’écran Choisir la source , sélectionnez la case d’option Créer à partir de l’URL , puis cliquez sur Suivant.

5. Dans l’écran Paramètres source , entrez l’URL de votre fichier de spécification d’API dans le champ URL .

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

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

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

NOTE

Si vous souhaitez vérifier la documentation de votre API avant de la publier, cliquez sur Fermer sur l’écran Terminer pour revenir à l’écran Documentation. Vous pourrez voir les brouillons de la documentation de votre API dans le volet Catégories et articles .

Génération de la documentation API avec un flux CI/CD

Avant de charger un fichier de spécification d’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 n’êtes pas familier avec Node.js, reportez-vous à this guide pour les instructions d’installation.

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

1. Accédez au projet souhaité dans le portail de la base de connaissances.

2. Sélectionnez API documentation ({ }) 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. La fenêtre contextuelle Nouvelle référence d’API s’affiche.

4. Dans l’écran Choisir la source , sélectionnez la case d’option Flux CI/CD , puis cliquez sur Suivant.

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

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

   • Le chemin d’accès complet à votre fichier de spécification JSON/YAML/YML local. 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 de l’API seragénérée.

NOTE

• La première ligne (npm install d360 -g) installe l’outil CLI Document360. Vous n’avez qu’à l’exécuter la première fois. S’il est déjà installé, vous pouvez sauter cette ligne.

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

Régénérer la documentation de l’API

Si vous apportez des modifications à votre API, telles que l’ajout de points de terminaison, vous n’avez pas besoin de mettre à jour manuellement la documentation de votre API dans Document360. Vous pouvez simplement régénérer la documentation de votre API, et toute modification de votre API sera automatiquement répercutée dans la documentation de l’API.

NOTE

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

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

1. Accédez au projet souhaité dans le portail de la base de connaissances.

2. Sélectionnez Documentation de l’API ({ }) dansla barre de navigation de gauche.

3. Cliquez sur Référence des documents API dans le volet de liste de gauche.

4. Cliquez sur l’icône Plus () en regard de la référence d’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 de l’API sera régénérée conformément au dernier fichier de spécification de l’API.

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

      • Cliquez sur Modifier.

      • Entrez la nouvelle URL dans le champ URL .

      • Cliquez sur Mettre à jour.

      • La documentation de l’API sera régénérée conformément au fichier de spécification de l’API dans la nouvelle URL.

Régénérer la documentation de l’API à partir d’un fichier de spécification d’API

1. Accédez au projet souhaité dans le portail de la base de connaissances.

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

3. Cliquez sur Référence des documents API dans le volet de liste de gauche.

4. Cliquez sur l’icône More () en regard de la référence d’API souhaitée pour laquelle vous souhaitez régénérer la documentation de l’API.

5. Cliquez Edit.

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

7. Cliquez sur Mettre à jour. La documentation de l’API sera régénérée conformément au dernier fichier de spécification de l’API.

Régénérer la documentation de l’API intégrée au flux CI/CD

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

Vous pouvez également effectuer la resynchronisation manuellement à l’aide de 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 de l’API

NOTE

Pour télécharger les fichiers API, assurez-vous que l’option Afficher la référence de l’API de téléchargement dans les paramètres du portail de la base de connaissances est activée.

Dépannage

URL de serveur manquante ou incorrecte dans OpenAPI

Erreur : Cette erreur se produit lorsque l’URL du serveur est manquante ou mal configurée dans la spécification OpenAPI. Par conséquent, les utilisateurs de l’API ne savent pas où envoyer des demandes d’API et le bouton « Essayer » peut ne pas être disponible dans la documentation de l’API. La cause première est généralement une section manquante ou incorrecte servers dans la spécification OpenAPI.

Étapes à suivre pour résoudre le problème

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

1. Définissez l’URL du 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 (Postman, cURL, etc.) utilisent l’URL de serveur correcte lors de l’exécution de requêtes.

NOTE

Les URL ci-dessus en sont des exemples. Reportez-vous à la configuration spécifique de votre API pour obtenir l’URL de serveur correcte.

Exemple:

Exemple YAML pour les 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 est correctement définie dans la spécification OpenAPI pour éviter aux consommateurs d’API d’avoir à construire manuellement les URL de demande d’API.

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

Erreur : Cette erreur se produit lorsque les demandes d’API renvoient une réponse non autorisée 401 . Cela se produit généralement lorsque l’URL du serveur incorrecte est utilisée dans les requêtes API. Par exemple, l’utilisation de https://apihub.document360.io instead of https://apihub.us.document360.io provoque des échecs d’authentification.

Étapes à résoudre :

Pour résoudre ce problème, procédez comme suit pour garantir une utilisation correcte de l’URL du serveur et une authentification correcte :

1. Assurez-vous que les demandes d’API utilisent le bon point de terminaison basé sur la région.

2. Vérifiez que l’ID client et la clé secrète client corrects sont utilisés.

Exemple d’une requête API correcte :

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

NOTE

L’URL ci-dessus est un exemple. Reportez-vous à la configuration spécifique de votre API pour obtenir l’URL de serveur correcte.

3. Assurez-vous que le jeton d’authentification est correctement inclus dans les en-têtes de la demande.

URL du serveur manquante dans la documentation de l’API

Erreur : ce problème se produit 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 n’indique 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 utilisateurs de l’API connaissent l’URL de base correcte :

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

Exemples:

Tableau comparatif : URL du serveur présente ou manquante

NOTE

Les URL ci-dessus en sont des exemples. Reportez-vous à la configuration spécifique de votre API pour obtenir l’URL de serveur correcte.

Pour éviter ce problème, assurez-vous que la documentation de l’API spécifie 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, le fait de cliquer sur la fonction Essayer entraîne une erreur 403. Cette erreur se produit lorsqu’il manque une définition pour le mécanisme de sécurité BearerAuth dans le fichier OAS.

Étapes à résoudre :

Pour résoudre l’erreur 403, procédez comme suit :

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

2. Si la définition de BearerAuth est manquante, incluez la définition de sécurité BearerAuth dans le fichier OAS et téléchargez-la à nouveau.

3. Au cours du processus d’importation, vérifiez si des alertes liées à l’authentification du porteur sont déclenchées et traitez-les en conséquence.

Style HTML incorrect dans la réponse de l’API

Lors de la récupération du contenu HTML d’un article via une API, la réponse est formatée au format JSON, qui utilise l’échappement (\") pour gérer certains caractères en toute sécurité. Cet échappement modifie les caractères tels que les guillemets, les barres obliques inverses et les sauts de ligne pour éviter les erreurs de transmission de données. Cependant, si les caractères échappés ne sont pas reconvertis (non échappés), la structure HTML peut être rompue, ce qui entraîne 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 sous la forme :

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

Les guillemets doubles échappés (\") garantissent que le JSON reste valide, mais s’ils ne sont pas échappés, le HTML peut ne pas s’afficher correctement.

Étapes à suivre pour résoudre le problème

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

2. Recherchez les caractères d’échappement dans la réponse JSON, tels que :

   • \" (guillemets doubles échappés)

   • \\ (barres obliques inverses échappées)

   • \n (nouvelle ligne)

   • \t (tab)

3. Annulez l’échappement du contenu JSON avant de l’afficher. Cela restaurera la structure HTML d’origine.

4. Vérifiez le style après avoir déséchappé pour vous assurer que le contenu s’affiche correctement.

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éséchappé, le code HTML s’affichera comme prévu, évitant ainsi les différences de style.

Les variables et les extraits ne s’affichent pas dans la réponse de l’API

Lors de la récupération du contenu d’un article via l’API, les variables et les 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 paramètre n’est "isForDisplay" pas défini correctement.

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

• Si elle n’est pas définie (ou non "isForDisplay" = false ), la réponse de l’API contiendra des variables et des extraits de code 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 de l’API sans "isForDisplay":

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

Les variables ne sont pas traitées, ce qui les rend impropres à l’affichage direct.

Réponse de l’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 l’API et inspectez la réponse.

2. Vérifiez si les variables ou les extraits de code apparaissent non traités dans la réponse.

3. Assurez-vous que la demande d’API inclut le "isForDisplay" paramètre. Si vous n’avez pas accès, modifiez la demande pour inclure "isForDisplay": true.

4. Envoyez la demande d’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 les extraits correctement rendus.

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

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

Corps vide affiché 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 peut être que le schéma OpenAPI ne contient pas l’attribut “type": "object” dans une ou plusieurs définitions d’objet.

Étapes à résoudre :

Assurez-vous que chaque définition d’objet dans votre spécification OpenAPI inclut “type": "object”. Cet attribut spécifie clairement que la structure définie est un objet, ce qui permet de maintenir la clarté et la cohérence de la documentation de votre API. Il permet aux outils de documentation d’API d’afficher avec précision les paramètres du corps de la requête, les schémas de réponse et d’autres définitions d’objet, ce qui permet aux développeurs de comprendre et d’interagir plus facilement avec votre API.

Liens utiles