Créer une documentation sur l’API

La création de la documentation d’API pour votre référentiel de code source est très importante. Une bonne documentation permet aux développeurs de comprendre, de gérer et d’utiliser facilement votre API. La documentation complète explique le fonctionnement de l’API, les entrées dont elle a besoin, les sorties qu’elle fournit et comment utiliser les points de terminaison d’API. Lors de la création de la documentation de l’API, vous devez choisir le meilleur format (comme la spécification OpenAPI ou Markdown), inclure des exemples et des scénarios d’utilisation, le maintenir à jour lorsque le code change et demander aux utilisateurs de l’API de formuler des commentaires afin de les améliorer. Bien que l’approche générale de la documentation des API fonctionne partout, il existe des différences entre Azure DevOps et GitHub.

Création d’une documentation d’API dans Azure DevOps

Pour ajouter efficacement la documentation de l’API à un projet Azure DevOps, vous devez utiliser un outil de documentation dédié qui fonctionne avec votre flux de travail de développement. Parmi les choix populaires, citons Swagger (OpenAPI), API Blueprint et les systèmes de documentation basés sur Markdown comme MkDocs ou Docusaurus. L’intégration d’Azure DevOps permet d’automatiser la création de la documentation et de la synchroniser avec votre code. La plupart des outils de documentation peuvent également lire des commentaires inline et les inclure dans la documentation générée automatiquement.

Vous devez publier la documentation de l’API dans un emplacement central auquel les membres de votre équipe et les parties prenantes peuvent accéder. Il peut s’agir d’un site web de documentation dédié, d’un wiki dans Azure DevOps ou d’un portail de documentation externe.

Vous pouvez également utiliser des annotations de code ou des décorateurs directement dans votre code pour ajouter des métadonnées qui décrivent vos points de terminaison d’API. Les outils tels que Swagger Codegen ou Springfox peuvent traiter ces annotations et créer des fichiers de spécification OpenAPI.

Configurez des processus automatisés dans azure Pipelines pour créer automatiquement la documentation de l’API chaque fois qu’une modification est apportée au code. Cela garantit que votre documentation reste actuelle et reflète les dernières modifications de vos API.

Création d’une documentation d’API dans GitHub

Lorsque vous utilisez GitHub, envisagez de créer la documentation de l’API à l’aide d’outils qui font partie de l’écosystème GitHub.

Commencez par documenter vos points de terminaison d’API, vos opérations, paramètres, réponses et toute autre information pertinente. Envisagez de créer cette documentation au format Markdown, car elle est largement prise en charge et facile à utiliser. Définissez une structure cohérente pour des 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.

Comme avec Azure DevOps, vous pouvez utiliser des générateurs de documentation ou des générateurs de sites statiques pour faciliter le processus de création de la documentation d’API à partir de fichiers Markdown. Parmi les choix populaires figurent Jekyll, MkDocs, Docusaurus et Hugo. Configurez le générateur pour lire les fichiers Markdown et créer des pages HTML statiques. Vous pouvez personnaliser la disposition, le thème et le style pour qu’il corresponde aux préférences et personnalisations de votre projet.

Pour publier le contenu HTML, utilisez GitHub Pages, ce qui vous permet d’héberger des sites web statiques directement à partir de votre dépôt GitHub. Vous pouvez créer une branche dédiée à cet effet et envoyer (push) les fichiers HTML dans cette branche. Vous pouvez également utiliser GitHub Actions pour générer et déployer automatiquement la documentation de votre API chaque fois qu’il existe une modification des fichiers de documentation ou du code.

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 code. Configurez le flux de travail Automation pour créer les fichiers de documentation HTML à l’aide de votre générateur de documentation choisi et déployez-les sur gitHub Pages.