Sesión - APIs con .NET 5 y Documentación con Swagger
Published: 2021-07-17 14:42:23

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](https://youtu.be/1csQbe6JppY)**, 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.

[![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9tjlpu4krfvtpwx78oh0.PNG)](https://youtu.be/1csQbe6JppY).

También te adjunto el repositorio en Github **[aquí](https://github.com/VeronicaGuaman/APIWhitSwagger)**, con el código fuente utilizado en la sesión y podrás encontrar también las diapositivas.

Nos vemos en [Twitter](https://twitter.com/veronicaguamann) e [Instagram](https://www.instagram.com/veronicaguamann/) ;)