Débuts dans la documentation API

Aperçu

La fonctionnalité de documentation API de Document360 vous offre une solution complète et complète pour publier, gérer et tester les références API. Que vous soyez une startup lançant sa première API publique ou une entreprise gérant des dizaines de microservices internes, Document360 transforme votre spécification OpenAPI en documentation pour développeurs soignée et interactive, sans nécessiter d'outils personnalisés ni de mise en forme manuelle.

Cet article couvre tout ce que vous devez savoir : configurer votre première référence API, choisir la bonne méthode d'importation, sécuriser les terminaux avec authentification, tester en direct avec Try It !, gérer les webhooks, exécuter des pipelines intégrés CI/CD, et suivre les bonnes pratiques qui distinguent les bons documents API des véritables excellents documents.

Qu'est-ce que la documentation API et pourquoi est-elle importante ?

La documentation de l'API est la référence technique qui indique aux développeurs exactement comment interagir avec votre API : quels points de terminaison existent, quels paramètres ils acceptent, quelles réponses ils renvoient, et comment fonctionne l'authentification. Contrairement aux articles de la base de connaissances générale, la documentation API suit un format strict et structuré dérivé d'un fichier de spécification lisible par machine (comme OpenAPI).

Pourquoi c'est important :

• Réduit le temps d'intégration. Les documents clairs réduisent l'intégration des jours à plusieurs heures. Les développeurs passent moins de temps à deviner et plus de temps à construire.

• Réduit la charge de soutien. Lorsque les documents répondent aux questions « comment m'authentifier ? » et « que signifie un 422 ? », votre équipe reçoit moins de tickets.

• Cela renforce la confiance des développeurs. Une documentation API incomplète ou obsolète signale un produit peu fiable. Une documentation de haute qualité est un signal direct de la qualité du produit.

• Permet l'auto-service. Les partenaires externes, clients et développeurs tiers peuvent s'intégrer sans avoir besoin d'accompagnement de votre équipe.

Documentation API vs. documentation classique

Dans Document360, la documentation de l'API se trouve dans un espace de travail dédié à l'API, séparé de votre base de connaissances standard. Cela permet différents contrôles d'accès, un routage et un branding pour votre contenu destiné aux développeurs.

Formats de spécification pris en charge

Document360 prend en charge les formats de spécifications suivants :

• OpenAPI 2.0 (anciennement Swagger)

• OpenAPI 3.0

• OpenAPI 3.1 (inclut la prise en charge des webhooks)

• Collections des facteurs

Les fichiers peuvent être téléchargés en JSON, YAML ou YML.

Choisir un format : Si vous partez à zéro, utilisez OpenAPI 3.1. C'est la norme actuelle, elle prend en charge les webhooks nativement, et possède l'écosystème d'outils le plus riche. Si vous migrez depuis une configuration Swagger 2.0 existante, Document360 l'accepte tel quel pendant que vous faites une mise à niveau progressive.

De plus, la fonctionnalité Essaie ! dans Document360 permet de tester directement les points de terminaison de l'API sur le Knowledge base site. La console interactive du site de la base de connaissances permettra aux développeurs d'entrer les paramètres nécessaires et d'exécuter des appels API, obtenant ainsi des réponses en temps réel. Cette fonctionnalité est utile pour dépanner et comprendre comment une API se comporte sans quitter la documentation ni écrire de code.

NOTE

La section Essayez ! prend en charge plusieurs schémas de sécurité simultanément, permettant aux utilisateurs de tester plus efficacement les points de terminaison nécessitant des méthodes d'authentification combinées.

Webhooks (événements) dans OpenAPI 3.1

Document360 prend en compte les webhooks définis dans OpenAPI 3.1. Les Webhooks apparaissent avec une icône d'événement dans votre référence API et incluent une section payload basée sur votre schéma. Si aucun exemple n'est fourni, Document360 affiche un exemple par défaut et une charge utile d'échantillon. Essayez, ce n'est pas disponible pour les webhooks. Les webhooks sont pris en charge pour le téléchargement de fichiers, l'importation d'URL et les flux CI/CD.

Intégration de la documentation API

Lors de l'inscription à Document360, les utilisateurs choisissent leur cas d'usage principal à l'étape 1 du processus d'intégration. Pour les utilisateurs souhaitant créer de la documentation API, Document360 offre une expérience d'intégration simplifiée. Si vous sélectionnez la documentation de l'API comme cas d'usage, vous serez redirigé vers le flux de configuration de l'API, où vous pouvez créer des références API en utilisant les options disponibles.

À l'étape 2 du flux d'intégration, vous disposerez de trois options pour créer une référence API :

• Fichier API d'upload : Prend en charge les fichiers JSON/YAML/YML (OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 et les collections Postman).

• Créer à partir d'une URL : Récupère automatiquement la spécification API depuis l'URL hébergée.

• Essayez un fichier API d'un magasin d'animaux : si vous n'avez pas de fichier API prêt, vous pouvez utiliser le fichier d'exemple (API du magasin d'animaux) proposé par Document360 pour remplir votre espace de travail.

Téléversement d'un fichier de définition d'API

Pour créer une référence API à partir d'un fichier de définition d'API, sélectionnez le bouton option Télécharger le fichier API. Ensuite, cliquez sur Télécharger depuis mon appareil ou glisser-déposer votre fichier de spécification API depuis votre appareil.

NOTE

Les formats de fichiers pris en charge pour le fichier de définition de l'API sont JSON, YAML ou YML.

Le système analysera le fichier et générera automatiquement la référence API.

• Si des alertes ou avertissements sont détectés dans le fichier téléchargé, un aperçu général sera affiché lors de l'intégration. Vous pouvez consulter des détails détaillés dans le portail de la base de connaissances, dans la section des journaux sous Plus d'options dans les références API.

• Si une erreur est détectée dans le fichier téléchargé (par exemple, format de fichier non supporté), remplacez le fichier téléchargé par un fichier alternatif.

Saisie d'une URL de documentation API

Pour créer une référence API à partir d'une URL de documentation API, sélectionnez le bouton Créer à partir de l'URL . Ensuite, saisissez l'URL de votre fichier OpenAPI dans l' URL de votre champ de définition d'API . Document360 récupérera et traitera la structure de l'API. Comme pour les téléchargements de fichiers,

• Si des alertes ou avertissements sont détectés, vous pouvez les consulter dans le portail de la base de connaissances, dans la section des journaux, sous Plus d'options dans les références API. Vous pouvez consulter des détails détaillés dans le portail de la base de connaissances, dans la section des journaux sous Plus d'options dans les références API.

• Si une erreur est détectée (par exemple, URL invalide), saisissez l'URL valide de votre fichier OpenAPI.

Sauter la configuration de l'API

Si vous choisissez l'option Essayer l'option de fichier API de la boutique d'animaux d'exemple ,

• Document360 créera automatiquement une référence d'API d'exemple (API de magasin d'animaux).

• Ce sera disponible en mode draft. Vous pouvez consulter les points de terminaison avant de publier ou télécharger votre fichier de spécifications et le publier plus tard.

Personnalisez votre base de connaissances

À l'étape 3, vous pouvez saisir l'URL de votre site web préféré. Si vous souhaitez sauter cette étape, le domaine sera par défaut celui lié à votre adresse e-mail d'inscription.

Lignes directrices de la marque

À l'étape 4, le nom de votre projet, la langue par défaut, le logo de marque et les couleurs de la marque sont automatiquement définis en fonction de l'URL fournie par vous. Cependant, vous pouvez modifier ces champs si nécessaire. Les paramètres de langue de votre navigateur déterminent la langue par défaut. L'anglais sera sélectionné par défaut si d'autres langues ne prennent pas en charge la langue de votre navigateur.

NOTE

• Si vous choisissez l'espagnol ou le portugais brésilien comme langue par défaut, la langue du portail sera définie en espagnol ou portugais brésilien. Sinon, l'anglais sera la langue par défaut.

• Le logo de la marque et les couleurs primaires/secondaires sont extraits de votre site web. Si vous choisissez de sauter cette étape, le nom du projet sera dérivé de votre adresse e-mail d'inscription, et le logo et les couleurs par défaut de Document360 seront appliqués.

Définir la confidentialité des documents

À l'étape 5, vous pouvez choisir les paramètres de confidentialité souhaités pour votre site :

• Privé : Restreignez l'accès à la base de connaissances afin que seuls les comptes d'équipe puissent consulter et interagir avec le contenu, en le maintenant sécurisé et interne.

• Publique : Rendez la base de connaissances accessible à tous, y compris aux utilisateurs externes, afin de permettre un accès libre à tout le contenu.

• Mixte : Combinez l'accès privé et public en permettant à certaines sections de la base de connaissances d'être visibles au public tout en limitant les autres sections aux comptes d'équipe.

Enfin, cliquez sur Suivant pour compléter votre flux d'intégration API.

Vous serez redirigé vers l'espace de travail de documentation de l'API, où :

• Vous verrez la référence API de la spécification API que vous avez fournie lors de l'intégration.

• Si vous n'avez pas fourni de spécification API, une référence API d'exemple (API de la boutique animale) sera disponible en mode brouillon.  

Techniques d'autorisation

Lors de l'interaction avec une API, il est important de s'assurer que seuls les utilisateurs autorisés peuvent accéder à certaines données ou effectuer des actions spécifiques. Cela se fait à l'aide de techniques d'autorisation, qui contrôlent l'accès et les permissions. Document360 prend en charge différentes méthodes d'autorisation pour sécuriser votre API, notamment :

• Authentification de base : nécessite un nom d'utilisateur et un mot de passe transmis dans la requête.

• Jeton porteur : S'authentifie avec un jeton généré après la connexion.

• Clé API : Utilise une clé unique, passée dans les en-têtes de requête, pour l'authentification.

• OAuth2 : Sécurise les API via divers flux tels que le code d'autorisation, le PKCE, les identifiants client et les flux implicites.

• OpenID Connect : Étend OAuth2 en ajoutant la vérification de l'identité utilisateur.

Considérations d'autorisation (OAuth2 et OpenID)

Lorsqu'on travaille avec des API utilisant OAuth2 ou OpenID pour l'autorisation, certains paramètres sont essentiels pour un bon fonctionnement.

• URI de redirection : C'est l'URL vers laquelle l'utilisateur sera redirigé après avoir terminé un flux d'autorisation. Assurez-vous de définir l'URI dans le format : domain/oauth. Par exemple : https://apidocs.document360.com/oauth.

• Renouvellement silencieux : Le renouvellement silencieux actualise automatiquement le jeton d'autorisation en arrière-plan, afin que les utilisateurs n'aient pas à se réauthentifier pendant leur session. Cela permet de maintenir leur session active sans interruption. Pour éviter que l'autorisation n'expire lors des sessions où les utilisateurs interagissent avec la fonction Essayez-le ! , Document360 renouvelle automatiquement le jeton de rafraîchissement en arrière-plan. Cela garantit que les utilisateurs n'auront pas à se réauthentifier manuellement.

Achats

Vous aurez accès à un espace de travail API dans le cadre de tous les forfaits payants Document360 (Professionnel, Professionnel et Entreprise). Si vous souhaitez acheter des espaces de travail API supplémentaires,

1. Naviguez dans () > portail de la base de connaissances > Facturation > Mon forfait.

2. Cliquez sur l'option Acheter.

3. Ajoutez le nombre souhaité d' espaces de travail de documentation de l'API. Examinez le coût de l'extension et le montant à dever.

4. Cliquez sur Confirmer le paiement pour procéder au paiement.

Dépannage

Problèmes d'accès à l'API

Erreur : erreur 400 – L'accès à l'API est désactivé. Veuillez contacter votre administrateur de projet.

Cette erreur se produit lorsque l'accès public à l'API est désactivé dans les paramètres du projet.

Étapes à résoudre :

1. Naviguez dans () > paramètres IA > Paramètres IA d'Eddy dans le portail de la base de connaissances.

2. Dans la section suite de recherche IA , assurez-vous que la case à cocher de l'API publique est cochée.

   

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

Problèmes d'importation d'API

Erreur : Format invalide – Téléchargement du fichier API échoué.

Cette erreur survient lorsqu'une ou plusieurs réponses dans le fichier de spécification OpenAPI manquent la section requise content .

Bien que le fichier puisse passer la validation dans Swagger Editor, Document360 applique des règles strictes de validation OpenAPI et exige que toutes les réponses définissent explicitement le type de média (par exemple, application/json) et la référence de schéma.

Étapes à résoudre :

1. Ouvrez votre fichier de spécification OpenAPI (Swagger) dans un éditeur de texte ou un IDE.

2. Localisez toutes les définitions de réponse qui sont vides ou qui font directement référence à un schéma sans content bloc.

   Exemple de réponse incorrecte :

   responses:
     "200": {}

3. Mettez à jour la définition de la réponse pour inclure une section de contenu avec le type de média approprié et la référence de schéma.

   Exemple de réponse correcte :

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/UserGroupFetchResponse"

4. Sauvegardez le fichier et essayez de le télécharger à nouveau sur Document360.

Résumé et balises non reflétés après l'importation d'une spécification API

Erreur : Les points de terminaison importés n'affichent pas les bons titres ni n'apparaissent dans les dossiers d'étiquettes attendus.

Ce problème survient lorsque les summary champs et tags de la spécification OpenAPI sont définis au niveau du chemin au lieu de sous l'objet d'opération (get, post, put, ou delete).

De plus, le tags champ doit toujours être écrit comme un tableau, même lorsqu'une seule balise est utilisée.

Étapes à résoudre :

1. Ouvrez votre fichier de spécification OpenAPI dans un éditeur de texte.

2. Déplacez les champs de résumé et d'étiquettes à l'intérieur de chaque objet d'opération.

3. Assurez-vous que la valeur des tags est écrite sous forme de tableau.

   Exemple incorrect :

   /dms/modules/{module-name}/types/logical/{logical-type}:
     summary: Type & Logical type
     tags: Logical Types
     get:
       ...
   

   Exemple correct :

   /dms/modules/{module-name}/types/logical/{logical-type}:
     get:
       summary: Type & Logical type
       tags: ["Logical Types"]
       ...
   

4. Après avoir effectué ces mises à jour, enregistrez le fichier et réimportez-le dans Document360.

   Les articles importés utiliseront désormais cette summary valeur comme titre de l'article, et les dossiers basés sur des étiquettes seront créés correctement.

La page d'accueil de la base de connaissances redirige vers  /apidocs après la mise à jour du compte

Erreur : La page d'accueil de la base de connaissances redirige vers  /apidocs et la page n'existe pas

Ce problème survient lorsqu'un espace de travail de documentation API est configuré sur l'accès public au lecteur.

Lorsque la base de connaissances est mise à jour, l'espace de travail de documentation de l'API peut être configuré en accès public au lecteur. En conséquence, les visiteurs de la page d'accueil de la base de connaissances sont automatiquement redirigés vers la /apidocs page, qui n'est pas créée par défaut.

Étapes à résoudre :

1. Naviguez dans () > Utilisateurs & Autorisations dans la barre de navigation de gauche du portail de la base de connaissances.

2. Dans le panneau de navigation de gauche, naviguez jusqu'à l'accès du lecteur.

3. Localisez l'espace de travail de documentation de l'API.

4. Réglez l'accès du lecteur en mode Privé.

Cela arrêtera la redirection involontaire et rétablira un accès normal à la page d'accueil de votre base de connaissances.

Vidéos associées

Découvrez notre documentation API moderne dans Document360 comme jamais auparavant

Endpoints API de test directement depuis la Documentation avec la fonction Essayer

Informations complémentaires

Présentation de la documentation API : Améliorez votre expérience API - Cliquez pour lire