Introducción
Documentar el software que compila tiene muchas ventajas. La documentación sólida no solo hace que el código sea más fácil de mantener con el tiempo, sino que también resulta más consumible por otros usuarios. Hacer que el código sea más consumible es especialmente importante cuando tiene una API que quieren usar otros usuarios. Afortunadamente, existen herramientas y marcos de trabajo que reducen el costo de producción de una buena documentación.
Supongamos que es el jefe de desarrollo para una empresa de enmarcado de láminas. Su empresa decide que sus API estén disponibles públicamente. Muchas de las API no tienen ninguna documentación existente y es su responsabilidad documentarlas. Documentar las API facilita que los asociados las usen correctamente, lo que da lugar a unos costos de mantenimiento y soporte técnico menores.
Necesita una manera sencilla y estandarizada de documentar cada API. También necesita un método para hospedar la documentación en una ubicación accesible para los asociados.
En este módulo, aprenderá a documentar una API de ASP.NET Core existente mediante Swashbuckle, Swagger, Swagger UI y OpenAPI.
Objetivos de aprendizaje
En este módulo, aprenderá a:
- Reconocer aspectos de Swashbuckle, OpenAPI y Swagger UI.
- Habilitar OpenAPI para una API de C#/ASP.NET Core.
- Usar Swashbuckle en una API de C#/ASP.NET Core.
- Generar y ver la documentación de la API, con OpenAPI.
Requisitos previos
- Experimentar con el diseño y la implementación de la API REST.
- Experimentar con el desarrollo de aplicaciones básicas de ASP.NET Core.
- Instalaciones locales del SDK de .NET, Visual Studio Code y la extensión de C# para Visual Studio Code.