Sesión - APIs con .NET 5 y Documentación con Swagger

Hola a todos :D
En esta ocasión abordamos el tema de como podemos documentar nuestras APIs hechas en ASP.NET 5 con Swagger.

Partiendo desde las bases podemos tratar los temas a breves rasgos para dar un contexto a la parte netamente técnica que se trato en la sesión.

Iniciamos definiendo que es una API(Application Programming Interfaces) en palabras breves, como su nombre lo indica es una Interfaz que permite la comunicación entre aplicaciones.
Las APIs permiten que nuestros productos y servicios se comuniquen con otros, sin necesidad de saber cómo están implementados.

Podemos construir APIs, para el consumo de nuestras aplicaciones privadas(móviles, web), internas de la empresa o podemos consumir APIs públicas(APIs externas).

Por otra parte, si desarrollamos nuestras APIs, un paso super importante y una buena práctica es realizar su documentación, ya que estas APIs van a ser consumidas por terceras personas, ya sea porque es una API pública, o va a ser consumida por el equipo de Frontend.

El documentar ayudará a que las personas que van a consumirla puedan entender que van a consumir, que parámetros deben ingresar, cual va a ser la respuesta que van a obtener
O como paso fundamental para nosotros como desarrolladores la documentación nos ayuda a recordar que hicimos, como lo hicimos y a futuro poder realizar mejoras y nuevas versiones.

En este punto entra el termino de Swagger, que es una herramienta basada en el estándar OpenAPI que nos permite documentar y probar nuestros Web APIs de forma accesibles y entendibles por los usuarios o desarrolladores que pretendan utilizarlos.

Con esta premisa, y entrando ya al tema, en .NET con ASP.NET podemos crear APIs fácilmente, ya que nos proporciona una plantilla basada en MVC(aunque no tenga vistas) para poder crearla rápidamente e ir construyendolas.

También nos proporciona herramientas para realizar la documentación utilizando Swagger, para esto existen paquetes Nugget, Swashbuckle y NSwag (en esta ocasión utilizaremos Swashbuckle).

Podemos agregarla mediante consola o por el administrador de paquetes Nugget y realizar algunas configuraciones en el Startup de nuestro proyecto para poder visualizarlo e iniciar con la documentación(como lo menciono en el video).

Y un punto super importante que podemos mencionar es que a partir de la versión ASP.NET 5 Swagger viene incorporada en la plantilla de nuestras APIs, así que no necesitaremos hacer nada, prácticamente tenemos todo configurado para iniciar a documentar.

En la sesión tratamos estos temas teóricos a detalle, por eso solo menciono lo más reelevante en este post.

Dicho todo esto, adjunto todos los recursos que utilizamos en la sesión:

Te dejo el video de la sesión aqui, en el que revisamos un poco de teoría como introducción, posteriormente realizamos la DEMO con un ejemplo de como podemos documentar nuestra API.