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 arrivent à 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 étiquette en catégories et sous-catégories, avec une étiquette de méthode (GET, POST, PUT, PATCH, DELETE) à côté de chaque. Les lecteurs filtrent par nom pour accéder rapidement à un point de terminaison.
• 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.
• Exact - Panneaux de code et de 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 à copier pour le point de terminaison, et les lecteurs peuvent changer de 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éponses 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, ). 500Les 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 de quelque chose que les lecteurs ont lu en quelque chose qu’ils peuvent exécuter. 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 temps réel - statut, timing, en-têtes et corps, sans quitter la page ni écrire de code. Voir Tester les terminaux avec Try it ! pour la solution complète.

Authentification

Les lecteurs fournissent les 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 affiche les champs appropriés pour chacun. Voir Autoriser les requêtes dans la console Try It pour plus de détails sur 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 point de terminaison de la référence avec un {{placeholder}}. Cela évite de retaper des valeurs communes lorsqu’elles passent d’un point à un autre. Voir Utiliser les variables dans la console Essay.

Eddy AI

Eddy AI est intégrée à la référence pour que les lecteurs puissent poser des questions sur un point de terminaison - 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 API.

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

La documentation 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 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 :

• Cela réduit le temps d’intégration. Des documents clairs réduisent l’intégration de jours à plusieurs heures. Les développeurs passent moins de temps à deviner et plus de temps à construire.
• Réduit la charge de support. Quand les documents répondent aux questions « comment m’authentifier ? » et « que signifie un 422 ? », votre équipe reçoit moins de tickets.
• Crée 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 API se trouve dans un espace de travail dédié à l’API, distinct de votre base de connaissances standard. Cela permet différents contrôles d’accès, routages et branding pour votre contenu destiné aux développeurs. Pour une référence complète de tous les points de terminaison 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 3.2
• OpenAPI 3.1 (inclut la prise en charge des webhooks)
• OpenAPI 3.0
• OpenAPI 2.0 (anciennement Swagger)
• Collections des facteurs

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

OpenAPI 3.2 ajoute la prise en charge de :

• La méthode HTTP QUERY pour les opérations de lecture nécessitant un corps de requête
• Catégories imbriquées générées automatiquement à partir de hiérarchies de tags
• Le flux d’autorisation de dispositif (RFC 8628) en tant qu’option OAuth2 supplémentaire
• Schémas de réponse en streaming pour les événements envoyés par serveur et les lignes JSON
• Serveurs nommés, valeurs d’exemple plus riches et URI de documents canoniques ($self)

Webhooks dans OpenAPI 3.1

Document360 prend en charge 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’exemple. 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 auprès de l’API client Document360, vous aurez besoin d’un jeton API. Pour plus d’informations, consultez 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