Introduction
Documenter le logiciel que vous créez présente de nombreux avantages. Une bonne documentation rend votre code plus facile à gérer au fil du temps. Elle permet aussi à d’autres personnes de le consommer plus aisément. Le fait de rendre votre code plus consommable est particulièrement important quand d’autres personnes souhaitent utiliser votre API. La bonne nouvelle, c’est qu’il existe des outils et des frameworks permettant de réduire les coûts de production d’une documentation de qualité.
Prenons un exemple. Vous êtes développeur dans une société d’encadrement qui décide de rendre ses API accessibles au grand public. Vous êtes donc chargé(e) de documenter vos API, la plupart d’entre elles ne disposant d’aucune documentation. Le fait de proposer des API documentées permet à vos partenaires de les utiliser plus facilement, réduisant ainsi les coûts de support et de maintenance.
Vous avez besoin d’une méthode simple et standardisée pour documenter chaque API. Vous avez également besoin d’une méthode pour héberger la documentation dans un emplacement accessible aux partenaires.
Dans ce module, vous apprenez à documenter une API ASP.NET Core existante avec Swashbuckle, Swagger, Swagger UI et OpenAPI.
Objectifs d’apprentissage
Dans ce module, vous allez :
- En savoir plus sur Swashbuckle, OpenAPI et Swagger UI
- Activer OpenAPI pour une API C#/ASP.NET Core
- Utiliser Swashbuckle pour une API C#/ASP.NET Core
- Générer et consulter une documentation d’API avec OpenAPI
Prérequis
- Savoir concevoir et implémenter une API REST.
- Savoir développer des applications ASP.NET Core simples.
- Installations locales du SDK .NET, de Visual Studio Code et de l’extension C# pour Visual Studio Code.