--- title: "Débuts dans la documentation API" slug: "getting-started-with-api-documentation" updated: 2026-09-29T08:31:42Z published: 2026-09-29T08:32:11Z canonical: "docs.document360.com/getting-started-with-api-documentation" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.document360.com/llms.txt > Use this file to discover all available pages before exploring further. # Débuts dans la documentation API Ce guide vous guide dans la publication de votre première API dans Document360, depuis le téléchargement de votre fichier spec jusqu’à un portail développeur interactif et en direct. À la fin de cet article, vous aurez : - Une référence API générée à partir de votre spécification OpenAPI - Vos endpoints sont visibles et consultables par les développeurs - La console interactive Try It ! prête pour les tests d’API en direct NOTE La documentation API est disponible sur tous les forfaits payants. Chaque forfait payant comprend un espace de travail API. Des espaces de travail supplémentaires peuvent être achetés en tant qu’extensions. --- ## Prérequis Avant de commencer, assurez-vous d’avoir : - **Un abonnement Document360**. - **Un fichier de spécification API** dans l’un de ces formats : OpenAPI 3.2, OpenAPI 3.1, OpenAPI 3.0, OpenAPI 2.0 ou Postman Collection, soit en fichier local (JSON, YAML ou YML), soit hébergé sur une URL d’où vous importerez. - **Accès au portail de la base de connaissances** avec les autorisations de création de contenu. NOTE Si vous n’avez pas encore de fichier de spécifications, vous pouvez toujours suivre ce guide en utilisant l’exemple de fichier API de la boutique d’animaux fourni par Document360. Vous serez invité à l’utiliser lors de la configuration. --- ## Naviguez vers l’espace de travail de documentation de l’API 1. Connectez-vous à Document360 et ouvrez votre projet dans le portail de la base de connaissances. 2. Dans la barre de navigation de gauche, cliquez **sur documentation** `{ }`API . Cela ouvre l’espace de travail dédié de l’API, séparé de votre base de connaissances standard. 3. Dans la barre de navigation du haut, cliquez sur le menu **déroulant Créer** et sélectionnez **Nouvelle API**. Cela ouvre la fenêtre de référence de la Nouvelle API. ![The API documentation workspace in the Knowledge base portal with the Create dropdown open showing the New API option.](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/API%20doc%20from%20portal.png) NOTE Vous pouvez créer un maximum de 3 références API dans chaque espace de travail API. --- ## Choisissez comment importer votre spécification Document360 prend en charge deux façons d’importer votre fichier de spécifications : **le téléchargement de fichier** et **l’importation d’URL**. Le flux CI/CD n’est pas une méthode d’importation distincte ; c’est un moyen d’automatiser l’une ou l’autre de ces deux méthodes afin que votre documentation se mette à jour automatiquement à chaque changement de spécification. | Méthode | Quand l’utiliser | Comment ça fonctionne | | --- | --- | --- | | Téléchargement de fichier | Vous avez le fichier de spécifications localement sous forme JSON, YAML ou YML. | Téléchargez le fichier directement. C’est idéal pour démarrer rapidement ou pour des mises à jour peu fréquentes. | | Importation d’URL | Votre spec est hébergée sur une URL publique ou interne stable. | Pointez Document360 vers l’URL. Vous pouvez resynchroniser manuellement depuis la même URL chaque fois que la spécification change. | | Flux CI/CD | Vous voulez que la documentation se mette à jour automatiquement à chaque changement de spécification. | Automatise le téléchargement de fichiers ou l’importation d’URL via la CLI d360 dans votre pipeline. Cela nécessite Node.js. | --- ## Téléchargez votre cahier des charges ### Téléverser un fichier 1. Dans la fenêtre de référence de la nouvelle API, sélectionnez l’option **Télécharger la définition de l’API** . 2. **Cliquez sur Télécharger depuis mon appareil** ou glisser-déposer votre fichier. Formats pris en charge : JSON, YAML, YML. 3. Document360 analyse le fichier et génère automatiquement la référence API. Si des avertissements sont détectés, une section Alertes et Avertissements apparaît — élargissez-la pour les examiner. Vous pouvez consulter tous les détails plus tard dans la section Journaux. 4. Cliquez sur **Nouvelle référence API** pour continuer. ![The New API reference window with the Upload API definition option and the upload area.](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/ways%20to%20add%20api.png) ### Importation à partir d’une URL 1. Dans la fenêtre de référence de la nouvelle API, sélectionnez l’option **Créer à partir de l’URL** et cliquez **sur Suivant**. 2. Entrez l’URL pointant vers votre fichier de spécification OpenAPI dans le champ URL. 3. Document360 récupère et traite la spécification. Si des avertissements sont détectés, ils seront disponibles dans la section Journaux après importation. 4. Cliquez **sur Ajouter une référence API** pour continuer. ### Utiliser le flux CI/CD NOTE Cette option nécessite Node.js installation sur votre système. 1. Dans la fenêtre de référence de la nouvelle API, sélectionnez l’option **CI/CD Flow** . 2. Copiez la commande CLI complète affichée dans la fenêtre. 3. Dans la commande copiée, remplacez la `--path` valeur par le chemin complet vers votre fichier de spécification local ou une URL valide y pointant. Par exemple : ``` --path=/Users/yourname/projects/api/openapi.yaml ``` Ou une URL : ``` --path=https://example.com/api/openapi.yaml ``` 1. Collez la commande mise à jour dans votre terminal et appuyez sur Entrée. Document360 télécharge votre spécification et génère la documentation de l’API. NOTE La première ligne de la commande CLI (`npm install d360 -g`) installe l’outil CLI Document360. Vous n’avez besoin de l’exécuter qu’une seule fois. Si elle est déjà installée, vous pouvez passer cette ligne. Si vous régénérez votre clé API, vous devez mettre à jour la `--apiKey` valeur dans votre commande CLI avant de l’exécuter à nouveau. L’ancienne clé ne sera plus valide. #### Pas de fichier de spécifications ? Utilisez l’API exemple de la boutique animalerie Si vous n’avez pas de fichier de spécification prêt, sélectionnez **Essayer un fichier API d’exemple de la boutique animale** quand on le demande. Document360 créera automatiquement une référence API d’exemple en mode brouillon. Vous pouvez l’explorer puis la remplacer par votre propre spécification plus tard. --- ## Consultez les alertes et avertissements Après avoir téléchargé votre spécification, Document360 vous montre un résumé du nombre de catégories et d’articles créés, ainsi que toute alerte ou avertissement détecté dans votre fichier. - **Les alertes et avertissements** signifient que la spécification a été importée, mais certains éléments peuvent ne pas s’afficher comme prévu. Vous pouvez consulter tous les détails dans la section Journaux : allez à votre référence API, cliquez sur l’icône Plus `(⋯)` , et sélectionnez Journaux. - **Les erreurs** signifient que l’importation a échoué. La cause la plus fréquente est un format de fichier non pris en charge ou une URL invalide. Remplacez le fichier ou corrigez l’URL et réessayez. ## ![The import summary showing created categories and articles with the Alerts and Warnings section.](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/view%20logs.png) ## Publiez votre référence API Après que votre spotter ait été traité avec succès : 1. Une fenêtre de confirmation affiche le nombre de catégories et d’articles créés. **Cliquez sur Publier** pour activer la référence API. 2. Si vous souhaitez revoir le contenu avant de publier, cliquez **sur Fermer**. Votre référence API est enregistrée en mode brouillon et visible dans le volet Catégories & Articles. ![The confirmation window showing the number of categories and articles created, with the Publish button.](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/review%20api%20and%20publish.png) NOTE Le mode brouillon est utile si vous souhaitez ajouter du contenu personnalisé à chaque article endpoint avant de les rendre publics. Tout contenu personnalisé que vous ajoutez sera conservé lorsque vous régénérerez ou resynchroniserez votre documentation. --- ## Configurez l’authentification pour Try It ! La console Try It ! permet aux développeurs de tester vos points de terminaison API directement depuis la documentation. Pour que cela fonctionne correctement, la méthode d’authentification doit être définie dans votre spécification et configurée dans Document360. Document360 prend en charge les méthodes d’authentification suivantes : | Méthode | Comment ça fonctionne | | --- | --- | | Authentification de base | Nom d’utilisateur et mot de passe passés dans l’en-tête de la requête. | | Jeton porteur | Un jeton généré après la connexion est passé dans l’en-tête d’Authorization. | | Clé API | Une clé unique passait dans les en-têtes de requête. | | OAuth2 | Prend en charge le code d’autorisation, le PKCE, les identifiants clients et les flux implicites. | | OpenID Connect | Étend OAuth2 pour ajouter la vérification de l’identité utilisateur. | NOTE La console Try It ! prend en charge simultanément plusieurs schémas de sécurité, permettant de tester les points d’accès nécessitant des méthodes d’authentification combinées. ### OAuth2 et OpenID Connect : configuration supplémentaire Lors de l’utilisation d’OAuth2 ou OpenID Connect, deux paramètres sont nécessaires : - **Redirigez l’URI** — Réglez ceci dans votre fournisseur OAuth à `domain/oauth`. Par exemple : `https://apidocs.yourdomain.com/oauth`. - **Renouvellement silencieux** — Document360 actualise automatiquement le jeton d’autorisation en arrière-plan lors des sessions actives Essayez-le !, afin que les utilisateurs n’aient pas besoin de se réauthentifier manuellement. NOTE Si le bouton Essayer ! n’est pas visible sur votre site de base de connaissances, vérifiez que la variable serveur et l’URL du serveur sont correctement définies dans votre fichier de spécification API. Sans cela, la fonctionnalité Essayez ! ne fonctionnera pas. --- ## Définir l’accès des lecteurs et la confidentialité Contrôlez qui peut voir votre référence API publiée en configurant les paramètres d’accès au lecteur. | Cadre | Ce que cela signifie | | --- | --- | | Privé | Seuls les utilisateurs peuvent consulter la référence de l’API. À utiliser pour les API internes ou uniquement pour les partenaires. | | Public | N’importe qui peut accéder à la référence API sans authentification. | | Mixte | Certaines sections sont publiques, d’autres sont réservées aux utilisateurs. | Pour configurer l’accès des lecteurs, allez dans **Paramètres** > **Utilisateurs et permissions** > accès au **lecteur** dans le portail de la base de connaissances, et localisez votre espace de travail de documentation API. IMPORTANT Visiter `/apidocs` avant la publication de tout article endpoint vous donnera une erreur 404 — il n’y a pas encore de contenu à afficher. Cela s’applique également si vous avez ajouté un lien `/apidocs` de navigation sur votre site de base de connaissances. Publiez au moins un article endpoint avant de rendre votre référence API accessible aux lecteurs. Application Programming Interface - A set of defined rules and protocols that allows one software application to communicate with and request functionality from another. APIs are the backbone of modern integrations. When Document360 connects to Slack, Intercom, or Google Analytics, it does so through their APIs. Document360 also provides its own REST API, enabling teams to programmatically manage articles, categories, and reader accounts from external systems.