Créer une documentation sur l’API
La documentation à l’API d’un référentiel de code source est essentielle pour fournir une précision, une accessibilité et une facilité d’utilisation aux développeurs qui maintiennent et consomment l’API. Une documentation complète sert de guide pour comprendre la fonctionnalité, les entrées, les sorties et l’utilisation des points de terminaison d’API. Lorsque vous documentez l’API, vous devez sélectionner le format de présentation le plus approprié (tel qu’une spécification OpenAPI ou Markdown), notamment des exemples et des scénarios d’usage, maintenez-la à jour avec des modifications de code et obtenez les commentaires de clients de l’API pour continuer à améliorer sa qualité.
Bien que l’approche générale pour documenter une API soit indépendante de la plateforme, il existe des différences dans son implémentation entre Azure DevOps et GitHub.
Documenter l’API dans Azure DevOps
Pour ajouter une documentation d’API à un projet Azure DevOps de la manière la plus efficace, vous devez envisager d’utiliser une plateforme ou un outil de documentation dédié qui s’intègre à votre workflow de développement. Des choix connus dans cette catégorie incluent Swagger (OpenAPI), API Blueprint et des systèmes de documentation basés sur Markdown tels que MkDocs ou Docusaurus. Leurs fonctionnalités d’intégration à Azure DevOps permettent d’automatiser le processus de génération de documentation, ce qui le maintient synchronisé avec le codebase. La plupart des outils de documentation prennent également en charge l’analyse de commentaires en ligne et les incluent dans la documentation générée automatiquement.
Vous devez publier la documentation d’API dans un emplacement centralisé accessible aux parties prenantes et aux membres de l’équipe. Il peut s’agir d’un site web dédié de documentation, d’un Wiki dans Azure DevOps ou d’un portail de documentation externe.
Vous pouvez également utiliser des annotations de code ou des éléments décoratifs directement au sein de votre code pour ajouter des métadonnées décrivant ses points de terminaison d’API. Des outils tels que Swagger Codegen ou Springfox sont en mesure de traiter ces annotations et de générer les fichiers de spécification OpenAPI.
Configurez des processus automatisés dans votre Azure Pipelines pour générer automatiquement une documentation d’API lorsqu’il existe une modification apportée au codebase. Cette opération veille à ce que votre documentation reste à jour et reflète les dernières modifications dans vos API.
Documenter l’API dans GitHub
Lorsque vous utilisez GitHub, envisagez de générer une documentation d’API en tirant parti d’outils faisant partie de l’écosystème GitHub.
Commencez par documenter les points de terminaison de votre API, les opérations, les paramètres, les réponses et toute autre information pertinente. Envisagez de créer cette documentation au format Markdown pour représenter sa large prise en charge et simplicité d’utilisation. Définissez une structure cohérente de documents individuels en les divisant en sections qui décrivent l’authentification, les points de terminaison, les paramètres de requête, les exemples de réponse, etc.
Quant à Azure DevOps, vous pouvez utiliser des générateurs de documentation ou des générateurs de site statiques pour rationaliser le processus de génération de documentation d’API à partir de fichiers Markdown. Des choix connus incluent Jekyll, MkDocs, Docusaurus et Hugo. Configurez le générateur pour analyser des fichiers Markdown et générer des pages HTML statiques. Vous pouvez personnaliser la disposition, le thème et le style pour faire correspondre les préférences et la personnalisation de votre projet.
Pour publier le contenu HTML, tirez profit des pages GitHub, qui vous permettent d’héberger des sites web statiques directement à partir de votre dépôt GitHub. Vous pouvez créer à cette fin une branche dédiée et envoyer (push) les fichiers HTML vers cette branche. Vous pouvez également implémenter GitHub Actions pour générer et déployer automatiquement votre documentation d’API lorsqu’il existe une modification apportée au codebase ou aux fichiers de la documentation.
Configurez GitHub Actions pour générer et déployer automatiquement votre documentation d’API chaque fois qu’une modification est apportée aux fichiers de documentation ou au codebase. Configurez le workflow d’automatisation pour générer les fichiers de documentation HTML en utilisant le générateur de documentation choisi et les déployer vers GitHub Pages.