Creando un API en Net Core - Creando un cliente para nuestro API
Tags: csharp, api, dotnet, rest
Published: 2021-04-09 22:28:26

En el artículo [anterior](https://dev.to/andreslozadamosto/creando-un-api-en-net-core-5-openapi-swagger-3fe3) vimos como agregar _Swagger_ y _Open API_ junto con la librería _Swashbuckle_ en nuestros proyectos de **APIs**. Es el momento de ver las opciones que tenemos para generar clientes que consuman nuestro **API** desde diferentes lenguajes de programación.

En primer lugar veremos como generar el archivo _JSON_ con la especificación de _Open API_  de nuestro **API** de forma que lo podamos guardar físicamente para su uso posterior, ya sea para generar los clientes como para utilizarlo en cualquier otro tool de **APIs**.

Luego, con la ayuda de _NSwagStudio_ vamos a crear clientes en lenguajes _Typescript_ y _C#_ junto con un pequeño ejemplo de como utilizarlos.

Por último, vamos a generar generar clientes en otros lenguajes como _Java_, _NodeJS_ y _Python_.

Les parece interesante? Vamos? 💪

*** 
# Generando Open API JSON
La librería _Swashbuckle_ nos provee de una _UI_ desde donde podemos obtener, entre otras grandes funcionalidades, el archivo _JSON_ con la documentación de _Open API_. Esta forma no es la más útil si estamos trabajando en un entorno de integración continua y nuestros _"Clientes"_ se generan de manera automática.

Por suerte _Swashbuckle_ nos provee un [tool](https://github.com/domaindrivendev/Swashbuckle.AspNetCore#swashbuckleaspnetcorecli) que nos ayuda a generar de una manera muy simple y totalmente compatible con entornos de _CI_.

Para ello, debemos instalar el _Global Tool_ posicionándonos en la carpeta del proyecto del **API** desde la línea de comandos y escribir lo siguiente.

```bash
dotnet tool install --version 6.1.1 Swashbuckle.AspNetCore.Cli
```

(Recomiendo antes de realizar su instalación revisar la versión más nueva o bien la correspondiente a la que se debe utilizar de acuerdo a la versión de _Net Core_ utilizada).

Una vez realizado el paso anterior podremos generar el archivo de la siguiente manera:

```bash
dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]
```

Donde

- `[output]`: Es el _Path_ donde queremos guardar el archivo generado
- `[startupassembly]`: Es el _Path_ donde se ubica la _DLL_ con el archivo de `startup.cs` del proyecto
- `[swaggerdoc]` Es el nombre que le dimos al documento _Swagger_ cuando lo incluimos en el `startup.cs` (`c.SwaggerDoc("MyFirstNetCoreRESTAPI" <--- es este nombre`).

En nuestro **API** de ejemplo el comando queda de la siguiente forma:

```bash
dotnet swagger tofile --output openapispec.json .\bin\Debug\net5.0\MyFirstNetCoreWebAPI.WebAPI.dll MyFirstNetCoreRESTAPI
```

Podemos ver el output del comando
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i5sbh22761yr3htqnqm4.jpg)

Primer paso completo, ya tenemos el archivo con la especificación de _Open API_ generado.

***

# NSwagStudio

[NSwagStudio](https://github.com/RicoSuter/NSwag/wiki/NSwagStudio) es una herramienta de _NSwag_ para la creación de clientes en lenguajes _CSharp_ y _TypeScript_ (con opción a exportar listo para usar desde _Angular_, _React_, etc) de un **API** a partir de un archivo en formato _Open API_ .

Este programa nos permitirá guardar la configuración de la generación de los **API** en un archivo _.nswag_ para poder utilizarlos todas las veces que sean necesarias.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/f4z649keyxnopnphev1n.jpg)

Podemos seleccionar desde donde queremos obtener la información del **API**, ya sea desde un archivo físico, una URL, binarios, etc e indicar el Runtime de _.Net Core_ o _.Net Framework_.

La configuración para la creación del **API** provee una gran cantidad de opciones la cual podremos ver en otro artículo.

En nuestro proyecto de **API** ejemplo (que pueden descargar desde [Github](https://github.com/andreslozadamosto/MyFirstNetCoreAPI-Tutorial)) creamos 2 nuevos proyectos.

- _MyFirstNetCoreWebAPI.WebAPI.Client_: El cual es un proyecto de librería donde colocamos el archivo _.swag_ y donde se va a generar el archivo con el código del cliente
- _MyFirstNetCoreWebAPI.ConsoleClient_: Es un proyecto de Consola para probar el cliente del **API**.

A gusto personal, prefiero que cada _controller_ del **API** tenga su propia _Interfaz_ e _implementación_ donde su _constructor_ reciba como parámetro una instancia de  _HTTPClient_. De esta manera podemos configurar el _HTTPClient_ de la manera que nosotros queramos, como por ejemplo agregarle un token de autenticación, políticas de retry (con Polly) y cualquier otra cosa que necesitemos de forma desacoplada del cliente.

La próxima vez que se actualice un _endpoint_ del **API** simplemente es necesario darle doble click al archivo _.nswag_ y generar nuevamente los archivos. Fácil no? 💪

Con esta configuración tenemos un cliente de nuestro **API** en una librería compartida que podremos utilizar desde cualquier proyecto de la solución o subirla a un repositorio de _Nuget_ para ser compartida entre diferentes proyectos.

Lo mismo podemos hacer para los clientes de _TypeScript_.

## NSwagStudio + CLI

_NSwagStudio_ nos permite generar los clientes ejecutando por línea de comando programa a partir de un archivo _.nswag_ de la siguiente manera:

```bash
nswag run /runtime:Net50
```

Este comando, claro, lo debemos ejecutar sobre la misma ubicación donde se encuentre el archivo _.nswag_ y en la [documentación](https://github.com/RicoSuter/NSwag/wiki/CommandLine) podemos ver todas las opciones que podemos pasarle.

Esta opción nos puede ser útil para entornos de **_CI_** o bien para agregarlo al _PostBuild_ del _MSBuild_.



## NSwagStudio + MSBuild

La generación de los clientes también podemos agregarla como un Task del _MSBuild_.

En mi caso particular no es la opción que mas me gusta pero se que a muchos les es muy útil.

Pueden ver toda la documentación [aquí](https://github.com/RicoSuter/NSwag/wiki/NSwag.MSBuild)



## NSwagStudio +  Otras alternativas

En entornos de **CI** podemos instalar _NSwagStudio_ por medio de _Chocolatey_ y ejecutarlo por medio del _CLI_ tal como vimos antes, pero la restricción que tenemos es que no queda tan "standard" para un _Pipeline_ de Build.

La opción en estos casos podemos utilizar otras altenativas

### NodeJS

Podemos utilizar el [npm package](https://www.npmjs.com/package/nswag) oficial para instalarlo en el **CI**, **Docker**  o desde donde sea necesario y ejecutarlo desde allí

### Docker

Otra opción es utilizar **Docker**, ya se para integrarlo en un stage del docker que compila la aplicación en el _Pipeline_ o en un paso separado. En este caso tenemos dos opciones, o bien utilizar la versión de _NodeJS_ como vimos recién o utilizar el ejecutable sobre _NetCore_.

En el proyecto  _MyFirstNetCoreWebAPI.ConsoleClient_ tenemos ahora un _Dockerfile_, un archivo _ClientGenerator-docker-net.nswag_ específico para ejecutarse dentro de _Docker_ y un archivo de _Json_ de _OpenAPI_ con la especificación del **API** que creamos en pasos previos.

El ejemplo del _Dockerfile_ es muy simple y sirve de base para que armen uno propio basado en sus necesidades. 

El detalle de cada paso que realiza el _Dockerfile_ esta explicado en el mismo archivo.

Veamos como lo ejecutamos

```bash
// creamos la imagen
docker build -t myfirstapi/nswag .
```

```bash
// corremos un container con la imagen
docker run -v ${pwd}:/resultado myfirstapi/nswag
```

Como pueden ver, en este último paso montamos el directorio actual en la carpeta _"resultado"_. Si no vieron el _Dockerfile_ les cuento que el _entrypoint_ realiza la exportación de los archivos de los clientes a esta carpeta que tenemos montada y de esta manera sacamos los archivos generados fuera del container.

Si quieren revisar como quedan los archivos, pueden ejecutar este comando para navegar el container.

```bash
docker run -it --entrypoint /bin/bash -v ${pwd}:/resultado myfirstapi/nswag
```



***

# OpenAPi Tools

La sección anterior vimos como generamos clientes para _TypeScript_ y _CSharp_, pero que pasa si necesitamos para otros lenguajes como _Java_ o _Python_? La respuesta es el generador oficial de _Open API_



Pueden revisar la cantidad infinita de generadores desde su web https://openapi-generator.tech/ y lo mejor es que pueden utilizar la versión de _NodeJS_ o bien proveen un _Docker_ para no tener que configurar nada y tenerlo funcionando de forma inmediata.

La verdad que iba a poner unos ejemplos, pero ya se hace muy largo el artículo. Dejen unos comentarios si quieren que el próximo artículo lo veamos 😁.