En el artículo anterior 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 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.
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:
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 destartup.csdel proyecto -
[swaggerdoc]Es el nombre que le dimos al documento Swagger cuando lo incluimos en elstartup.cs(c.SwaggerDoc("MyFirstNetCoreRESTAPI" <--- es este nombre).
En nuestro API de ejemplo el comando queda de la siguiente forma:
dotnet swagger tofile --output openapispec.json .\bin\Debug\net5.0\MyFirstNetCoreWebAPI.WebAPI.dll MyFirstNetCoreRESTAPI
Podemos ver el output del comando
Primer paso completo, ya tenemos el archivo con la especificación de Open API generado.
NSwagStudio
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.
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) 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:
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 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í
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 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
// creamos la imagen
docker build -t myfirstapi/nswag .
// 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.
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 😁.
Top comments (0)