Fondamentaux de l’API

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.

L’expérience du lecteur

Lorsque vous publiez une référence API, les développeurs tombent sur une page interactive à trois volets — et non un document statique. Comprendre cette mise en page vous aide à imaginer ce que vos lecteurs voient réellement, et vous oriente vers l’article qui explique chaque partie en détail.

• Gauche - arbre de navigation. Chaque point de terminaison dans votre spécification, regroupé par tag en catégories et sous-catégories, avec une étiquette de méthode (GET, POST, PUT, PATCH, DELETE) à côté. Les lecteurs filtrent par nom pour accéder rapidement à un point de départ.
• Centre - documentation. La description du terminaison, les paramètres de chemin et de requête, le schéma du corps de requête et les exigences d’authentification – tout est généré à partir de votre spécification.
• À droite - Panneaux Code et Réponse. Exemples de requêtes prêtes à l’emploi et exemples de réponses, côte à côte avec la documentation.

Panneau de codes

Le panneau Code affiche un exemple de requête prête à être copiée pour le point de terminaison, et les lecteurs peuvent changer le langage pour correspondre à leur pile. Six langues sont disponibles :

• cURL
• Coquille
• Python
• Java
• JavaScript
• C#

Chaque exemple est mis à jour pour refléter le chemin réel, les paramètres et l’authentification du point de terminaison, afin qu’un lecteur puisse le copier directement dans son propre environnement.

Panel de réponse

Le panneau Réponse montre des exemples de réponses pour le point de terminaison, organisées par code d’état (par exemple, réponses de réussite et d’erreur telles que 200, 401, 403, 404, 422, 429, 500). Les lecteurs sélectionnent un code d’état pour voir la forme de la réponse à laquelle ils doivent s’attendre dans chaque cas, ce qui facilite la gestion à la fois des chemins de réussite et d’erreur dans leur intégration.

Essaie

Try It transforme la référence d’un objet que les lecteurs ont lu en quelque chose qu’ils peuvent publier. Il ouvre une console interactive en ligne sur n’importe quel point de terminaison, permettant aux développeurs d’envoyer une vraie requête et de voir la réponse en direct – statut, timing, en-têtes et corps – sans quitter la page ni écrire de code. Voir Tests des terminaux avec Essayez ! pour la solution complète.

Authentification

Les lecteurs fournissent leurs identifiants directement dans la console Try It en utilisant le schéma défini par votre API — clé API, HTTP Basic, HTTP Bearer, OAuth 2.0 ou OpenID Connect. Try It lit les schémas de votre spécification et montre les champs appropriés pour chacun. Voir Autoriser les requêtes dans la console Essayer pour les détails de chaque méthode.

Variables

Les variables permettent aux lecteurs de stocker une valeur une fois, comme un ID ou un jeton, et de la réutiliser sur chaque extrémité de la référence avec un {{placeholder}}. Cela évite de retaper les valeurs communes lorsqu’elles passent d’un point de terminaison à l’autre. Voir Utiliser des variables dans la console Essayer.

Eddy AI

Eddy AI est intégrée à la référence pour que les lecteurs puissent poser des questions sur un endpoint – comment il fonctionne, comment s’authentifier, ou pour un exemple de code dans un langage spécifique et obtenir des réponses sans quitter la page. Voir Utiliser Eddy AI dans la référence de l’API.

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érales, la documentation API suit un format strict et structuré dérivé d’un fichier de spécification lisible par machine.

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. Pour une référence complète de tous les terminaux et schémas disponibles, consultez la documentation développeur de Document360.

Formats de spécifications 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.

Webhooks 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. Try It ! 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.

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. Document360 prend en charge les méthodes d’autorisation suivantes :

• Authentification basique - Nécessite un nom d’utilisateur et un mot de passe transmis dans la requête.
• Jeton porteur - 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 : Code d’autorisation, PKCE, identifiants clients et Implicite.
• OpenID Connect - Étend OAuth2 en ajoutant la vérification de l’identité utilisateur.

Pour authentifier les requêtes vers l’API client de Document360, vous aurez besoin d’un jeton API. Pour plus d’informations, voir l’article sur les jetons API .
Pour effectuer votre première requête API authentifiée avec Swagger, Postman ou curl, consultez la section Faire votre première requête.

OAuth2 et OpenID Connect : configuration supplémentaire

Lorsqu’on travaille avec des API utilisant OAuth2 ou OpenID Connect, deux paramètres sont nécessaires pour que Try It ! fonctionne correctement :

• URI de redirection - Réglez ceci dans votre fournisseur OAuth sur l’URL de rappel OAuth de la référence API : https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html.
• Renouvellement silencieux - Document360 actualise automatiquement le jeton d’autorisation en arrière-plan lors des sessions actives Try It !, afin que les utilisateurs n’aient pas besoin de s’authentifier manuellement.

FAQ