Saltar al contenido

Artículos, tutoriales, trucos, curiosidades, reflexiones y links sobre programación web ASP.NET Core, MVC, Blazor, SignalR, Entity Framework, C#, Azure, Javascript... y lo que venga ;)

17 años online

el blog de José M. Aguilar

Inicio El autor Contactar

Artículos, tutoriales, trucos, curiosidades, reflexiones y links sobre programación web
ASP.NET Core, MVC, Blazor, SignalR, Entity Framework, C#, Azure, Javascript...

¡Microsoft MVP!
martes, 4 de febrero de 2020
Open API Días atrás veíamos cómo utilizar Swashbuckle para generar automáticamente la descripción OpenAPI de APIs creadas con ASP.NET Core MVC y ponerlas a disposición de los consumidores en una ruta específica:
  Descripción OpenAPI de una API

En este post vamos a ver un par de formas de sacar provecho de esta descripción:
  • En primer lugar, usaremos Swagger UI para generar un sitio web interactivo de documentación y pruebas de nuestra API.
  • Después, veremos cómo generar desde Visual Studio código cliente para acceder a la API.

Swagger UI

Swagger UI es un proyecto open source que permite generar una web de documentación partiendo de la descripción OpenAPI de un servicio. Además esta web es interactiva, pues incluye la posibilidad de probar "in situ" las llamadas a los servicios.

Ponerlo en marcha es trivial: una vez tenemos instalado el paquete Swashbuckle.AspNetCore en nuestro proyecto y hemos configurado apropiadamente la generación de la definición OpenAPI (ya lo vimos en el post anterior), basta con añadir al pipeline el middleware encargado de generar la web:
...
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/api/swagger.json", "Awesomic calculator");
});
...
Fijaos que el endpoint que especificamos en la llamada a SwaggerEndpoint() es la ruta hacia la descripción OpenAPI de nuestro servicio.

Hecho esto, ya podemos utilizar la ruta "/swagger" para tener acceso a la documentación interactiva de la API:

Página de la API Calculator en Swagger UI

Pulsando sobre las operaciones del servicio de cálculo podemos acceder a la descripción completa de las mismas. Ahí encontraremos la información textual incluida en comentarios XML en el código, los parámetros de entrada, respuestas HTTP posibles, etc:

El servicio Divide en Swagger UI
Tipos de respuesta del servicio

Para probar en vivo el servicio, podemos pulsar el botón "Try it out"; podremos especificar el valor para los distintos parámetros de entrada, y acceder después a la información retornada desde el mismo:

Probando en vivo el servicio a través de Swagger UI

Generación de código cliente para acceder a la API

Visual Studio incluye herramientas para la generación de código cliente de las APIs definidas mediante OpenAPI. He de decir que a veces parecen no funcionar demasiado bien, pero al menos cumplen mínimamente su objetivo de ahorrarnos trabajo a la hora de implementar clientes de las API.

La generación se realiza partiendo de los esquemas JSON que describen los servicios, que pueden encontrarse ya en nuestro proyecto, o bien ser descargados utilizando el IDE, accediendo a la opción Dependencies > Add Connected Service > Service References; desde ese punto podremos añadir servicios OpenAPI simplemente indicando su ruta en el disco o la URL de su definición:

Añadir referencia a servicio OpenAPI

Tras ello, Visual Studio acudirá al origen indicado, descargará el archivo y lo añadirá al proyecto en la carpeta OpenAPI estableciendo su Build action a "OpenAPI file reference", lo cual asegurará que el cliente sea generado de forma automática:

Esquema OpenAPI añadido
Si, en lugar de dejar que Visual Studio descargue el esquema y lo incluya en el proyecto, preferimos incluirlo nosotros manualmente, para que todo funcione obligatoriamente tendremos que modificar la Build Action a la indicada.
En las propiedades del archivo JSON podemos establecer también determinadas opciones, como el nombre de la clase generada o el espacio de nombres en el que será incluida. En nuestro caso, podría ser razonable establecer el nombre de la clase generada y, opcionalmente, el namespace:

Esquema OpenAPI añadido

Es importante tener en cuenta que las clases generadas serán ubicadas en la carpeta "Obj" del proyecto, por lo que no estarán disponibles a nivel de código en la solución.

Una vez realizados los pasos anteriores, ya podemos utilizar directamente el cliente de la API. Como vemos en el siguiente código, se trata de una clase con el nombre que hemos indicado, que instanciamos suministrándole la URL base del servicio y la instancia de HttpClient que se utilizará internamente para realizar las llamadas:
class Program
{
    static async Task Main(string[] args)
    {
        var httpClient = new HttpClient();
        var x = new CalculatorApi("https://localhost:44329/", httpClient);
        var result = await x.DivideAsync(100, 10);
        Console.WriteLine(result);
    }
}
Publicado en Variable not found.

Aún no hay comentarios, ¡sé el primero!