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.
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
| Aspect | Documentation API | Documentation régulière |
|---|---|---|
| Public principal | Développeurs et intégrateurs techniques | Utilisateurs finaux, équipes internes |
| Structure | Piloté par un fichier de spécifications (OpenAPI, Postman) | Articles rédigés manuellement |
| Type de contenu | Points de terminaison, paramètres, schémas, méthodes d’authentification | Guides, tutoriels, articles conceptuels |
| Interactivité | Test en direct via Try It ! | Lecture statique |
| Versionnement | Liés aux versions des spécifications API | Géré éditorialement |
| Génération automatique | Oui, à partir du fichier de spécifications | Non |
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é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.
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.
La fonctionnalité Essaie ! dans Document360 permet de tester directement les points de terminaison de l’API sur le site de la base de connaissances. La console interactive permet aux développeurs d’entrer les paramètres nécessaires et d’exécuter des appels API, obtenant des réponses en temps réel, sans quitter la documentation ni écrire de code.
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 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.
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 :
- Redirection URI - Réglez ceci dans votre fournisseur OAuth sur le format
domain/oauth. Par exemple :https://apidocs.document360.com/oauth. - 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
En quoi la documentation API diffère-t-elle de la documentation classique ?
La documentation API est spécifiquement conçue pour expliquer les points de terminaison, l’authentification et les intégrations. Il est distinct des articles standards de la base de connaissances et utile pour le contenu destiné aux développeurs.
Qu’est-ce qu’une référence API ?
Une référence API est une ressource documentaire qui fournit des informations complètes sur les fonctions, classes, méthodes, paramètres, types de retour et autres composants d’une API. C’est un guide ou un manuel destiné aux développeurs qui souhaitent intégrer ou utiliser l’API dans leurs applications.
Quels sont les formats de fichiers de spécification pris en charge ?
Vous pouvez télécharger votre fichier de spécification sous forme d’URL, JSON, YAML ou fichier YML . Document360 prend en compte OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 et les spécifications de Postman.
Combien de références API puis-je créer ?
Dans chaque espace de travail API, vous pouvez créer un maximum de 3 références API.
Quel est l’ordre par défaut des catégories lors du téléchargement d’un fichier de spécification OpenAPI ?
Les catégories dans Document360 sont créées en fonction de l’ordre des tags défini dans votre fichier de spécifications. Par exemple, si votre spic définit des tags dans l’ordre Animal, Magasin, Utilisateur — les catégories apparaîtront dans le même ordre.
L’option « Essayez-le ! » n’est pas disponible sur le site de la base de connaissances. Quelle pourrait en être la raison ?
Si la fonctionnalité Essayez ! n’est pas visible, assurez-vous que la variable serveur et l’URL du serveur sont correctement définies dans votre fichier de spécification API. Sans ceux-ci, la fonctionnalité ne fonctionnera pas.
Les valeurs déroulantes de référence de l’API peuvent-elles être modifiées via l’interface utilisateur ?
Non. Les modifications des éléments de référence API telles que les valeurs déroulantes ne peuvent être effectuées que via le fichier de spécification OpenAPI. La modification de ces valeurs via l’interface utilisateur n’est actuellement pas prise en charge.
Vidéos associées
Découvrez notre documentation API moderne dans Document360
Test API endpoints directement depuis la documentation avec Try It !
Informations complémentaires
Lisez notre blog sur - Présentation de la documentation API : Améliorez votre expérience API