Documenter une API web ASP.NET Core avec les outils Swagger
Une API peut être d’une grande utilité, mais elle ne peut s’imposer auprès des développeurs que s’ils savent s’en servir. Les développeurs souhaitent aussi intégrer une API le plus rapidement possible. Une API bien documentée permet aux développeurs de comprendre ses fonctionnalités et son utilisation, ce qui rend son intégration plus efficace.
Jusqu’à présent, toute la documentation décrivant une API et son utilisation était rédigée à la main. Nous disposons maintenant d’une spécification standard pour les descriptions d’API appelée OpenAPI. Swagger UI propose des outils d’implémentation et de test de la spécification OpenAPI pour vos API. Swashbuckle est un package open source qui génère automatiquement les documents de description OpenAPI directement à partir de contrôleurs d’API web à l’aide de la réflexion .NET. Swashbuckle contribue à automatiser le processus de description, ce qui permet aux équipes de générer, de gérer et d’utiliser plus facilement la documentation des API basée sur OpenAPI. Décrivez simplement votre API et laissez les outils générer une documentation riche.
Qu’est-ce qu’OpenAPI ?
OpenAPI est une spécification utilisée pour décrire les API REST. Elle est indépendante du langage et vous permet de décrire votre API entière, notamment :
- Points de terminaison disponibles
- Paramètres d’opération
- Méthodes d’authentification
- Contact et autres informations
Vous pouvez écrire les spécifications de l’API en YAML ou JSON. Grâce à la spécification OpenAPI, les humains et les ordinateurs peuvent comprendre les fonctionnalités de votre API sans devoir accéder à son code source.
Qu’est-ce que Swagger ?
Swagger est un ensemble d’outils open-source reposant sur la spécification OpenAPI. Ces outils peuvent vous aider à concevoir, générer et documenter des API REST. Swagger utilise la spécification OpenAPI de votre API pour comprendre sa structure.
Par exemple, Swagger UI est un outil qui permet d’afficher la documentation dans un navigateur pour une API définie avec la spécification OpenAPI. Swagger Codegen peut prendre la même spécification OpenAPI d’une API et générer des SDK clients.
Qu’est-ce que Swashbuckle ?
Swashbuckle est une implémentation open source de Swagger qui permet de générer une documentation Swagger pour les API .NET Core à l’aide de la réflexion .NET.
Swashbuckle repose sur trois composants principaux :
Swashbuckle.AspNetCore.Swagger : ce composant est le modèle objet et l’intergiciel (middleware) Swagger permettant d’exposer des objets
SwaggerDocumenten tant que points de terminaison JSON.Swashbuckle.AspNetCore.SwaggerGen : cette bibliothèque est un générateur Swagger qui génère des objets
SwaggerDocumentdirectement à partir de vos routes, contrôleurs et modèles. La bibliothèque est généralement associée à l’intergiciel du point de terminaison Swagger pour exposer automatiquement un fichier JSON Swagger.Swashbuckle.AspNetCore.SwaggerUI : ce package est une version intégrée de l’outil Swagger UI. Il interprète le fichier JSON Swagger afin de créer une expérience enrichie et personnalisable permettant de décrire les fonctionnalités de l’API web. Il intègre des ateliers de test pour les méthodes publiques.
CLI Swashbuckle : Une fois installé, cet outil .NET global permet de générer des spécifications OpenAPI lors du processus de build et de publication. Vous trouverez un lien de téléchargement de Swashbuckle CLI à la fin de ce module.
Comme ces bibliothèques sont ajoutées à votre application, elles génèrent et visualisent la documentation de votre API à partir de la dernière version de votre API. Ainsi, une documentation vivante toujours synchronisée avec le code le plus récent, est créée.