OpenAPI en mi API REST .NET Core con “Swashbuckle”

imageOpenAPI es un estándar para crear, administrar y consumir API REST. Conocido previamente como Swagger, en el último año ha sido adoptado por la Linux Foundation y obtuvo el apoyo de compañías como Google, Microsoft, IBM, Paypal, etc. para convertirse en un estándar para las API REST.

Cuando creamos un API Rest, tenemos varias opciones durante el desarrollo para comprobar que ésta funciona.  Quizás la más ocurrente es utilizar directamente el navegador e ir cambiando la url de cada uno de nuestros servicios u operaciones.  El principal problema con esto es que en un equipo de trabajo, no nos acordaremos de las urls, por lo que se comparten o anotan en alguna wiki o se contemplan otras opciones muy similares.

Dentro de estas otras opciones nos encontramos con: Fiddler, Avadced REST Client (extensión de Chrome), o Postman entre otras herramientas, que nos facilitan esta labor en alguna u otra medida. Por supuesto, y al margen de los Test Integrados, que veremos en algún otro post (con xUnit), Postman es realmente la que mas me gusta y, en mi opinión, la más útil de todas. Además de hacer estas pruebas de las que comentamos, nos permite: diseñar APIs, crear Mocks, test automáticos, documentarlas y mucho más.

image

De igual forma, Open API, como estándar es la opción que estamos buscando, tanto para el “testeo” del que hablamos, como para ayudarnos con la documentación, para la exploración de APIs, e incluso para la auto-generación de SDKs.

Tanto Postman como OpenAPI, son herramientas complementarias, si bien, al crear nuestras propias API, el hecho de utilizar OpenAPI nos va a proporcionar:

  • Definición y documentación
  • Cumplimiento del standard
  • Auto-generar SDKs para que terceros puedan comunicarse
  • Personalización
  • Visualización
  • Ejecución y pruebas
  • Gratis para su uso
  • Y además, muy fácil de implementar en .NET

Al hablar de diseño de API y refiriéndonos a OpenAPI, implícitamente estamos hablando de JSON o YAML, dos formatos de ficheros también estándares, que van a permitirnos definir y diseñar las mimas. La versión actual de la especificación es la 3.0.1 y orientada a YAML y la versión previa la 2.0, que es idéntica a la especificación 2.0 de Swagger antes de ser renombrada a “Open API Specification”.

En el momento de escribir el post, el tooling para trabajar con la versión 3.0, aún es limitado.

Diseñando un API

Veamos como diseñar un API :

image

  • Una vez concluido el diseño, estamos en el momento de auto-generar, para diferentes lenguajes, el servidor: haskell, rails5, rust-server, spring, asp.net core, etc., y el cliente: eiffel, java, html, groovy, go, jmeter, scala, javascript, typescript-jquery, angular, C#,  etc.

image

  • Con el código resultante tras la auto-generación, tendríamos prácticamente, desde el día 1 de desarrollo, un API desplegada a modo de Mock. Importante, principalmente para desarrolladores Front, que necesitan un API, que probablemente no será desarrollada hasta una fase posterior. ¡IMPORTANTE Evitemos bloqueos entre equipos y tareas. Diseñemos APIs!

Nota: En esta URL: https://app.swaggerhub.com/apis/juanluelguerre/Taskin/v1, he publicado la versión 1.0 (muy sencilla) de Taskin, sobre la que podremos probar.

Creando APIs con NET Core y OpenAPI

Otra de las opciones, también importante es que si comenzamos un desarrollo desde cero, en base a una arquitectura propia y dependiente de cada proyecto, necesitaremos que el código auto-generado, se adecúe a la misma.  Para ello, tendremos dos alternativas:

  1. Trabajar con el SDK de OpenAPI y modificar las plantillas de auto-generación.
  2. Integrar OpenApi directamente en nuestro código .NET.

De acuerdo al objetivo de este Post, optaremos por la alternativa 2, donde para ellos seguiremos los siguientes pasos:

  • Crear un proyecto “ASP.NET Core Web Application”
  • Seleccionar el tipo de aplicación: API. Por el momento, no marcaremos la opción de Docker.
  • Para .NET Core 2.1, por defecto usamos HTTS, por lo que incluimos una nueva variable de entorno ASPNETCORE_HTTPS_PORT con el valor del puerto HTTS (ej: 5003) o bien la instrucción services.AddHttpsRedirection(options => options.HttpsPort = 5003);
  • Añadir la referencia al paquete NuGet: Swashbuckle.AspNetCore
  • Añadir el siguiente código al final del método “ConfigureServices(IServiceCollection services)” del fichero Startup.cs
  • Añadir el siguiente código al final del método “Configure(IApplicationBuilder app, IHostingEnvironment env)” del fichero Startup.cs.

image

  • En este punto podremos probar nuestra aplicación, sin necesidad de recordar la url de cada operación. Comprobaremos que de un simple string “[“value1”, “value2”]”  como resultado, pasamos a visualizar, navegar, ejecutar y depurar fácilmente.

image

Nota: Si navegamos al json “/swagger/v1/swagger.json”, es decir, a la url: https://localhost:5003/swagger/v1/swagger.json, obtenemos el “.JSON” correspondiente a la especificación OpenAPI, y,  al utilizarlo en el editor Online de Swagger, como vimos al principio del post, verificaremos, que nuestra API REST es correcta y por tanto cumple con el estándar.

image

Otra alternativa para la generación de Servidor y/o Cliente es “NSwag Studio”, que ya comentamos brevemente en un post anterior, se trata de una aplicación de escritorio, con ciertas opciones de personalización. Así mismo, también podemos utilizarla al igual que “Swashbuckle”, para integrarla en nuestra API REST .NET Core.

Y, para finalizar, si estas pensando en migrar tu especificación OpenAPI 2.0 a la versión 3.0, puedes utilizar esta herramienta: https://openapi-converter.herokuapp.com/

Espero que haya sido de utilidad

Saludos & Happy Coding!
Juanlu

¿Javascript ha muerto? .NET Web Assembly con Blazor

imageDurante el pasado fin de semana, entre algo de running, y alguna que otra fiesta, al fin he decidido aventurarme con Blazor.   Es cierto, que tengo pendiente otros “TO DOs”, como por ejemplo  profundizar en Angular y otros frameworks Javascript. Pero,… ¿Realmente lo necesitaré? ¡me pregunto!.

Como apasionado del mundo .NET, ¿Porque cambiar de lenguaje de programación para desarrollar Front? ¿Porque no desarrollar siempre con .NET?

Veamos a continuación si realmente Javascript ha muerto o estamos ante una nueva era/moda o simplemente una alternativa más ¿Quizás ha llegado ya el momento de que Web Assembly esté maduro?¿DLLs que se ejecutan en el navegador? 

¿Quieres saber más de todo esto? Continua leyendo, vayamos poco a poco conociendo estos nuevos conceptos.

¿Que es Web Assembly (abreviado Wasm)?

WebAssembly (Wasm) es un formato de código binario portable (bytecode), para la ejecución íntegra en navegador de scripts de lado del cliente. Se trata de un lenguaje de bajo nivel, diseñado inicialmente como formato destino en la compilación desde C y C++ entre otros.

El resultado de usar Wasm en lugar de Javascript, es una aplicación mucho más rápida, tanto durante la carga como en ejecución. ¿Quieres saber porqué? Echa un ojo a este enlace.

¿Que es Blazor?

Ahora que sabemos lo que es Wasm, podemos decir que Blazor es la implementación de Microsoft .NET para generar ensamblados Wasm.  Y, mas concretamente, un framework para la construcción de páginas web (SPA) basadas en .NET (C# y Razor Pages) y HTML  que se ejecuta en el navegador a través de WebAssembly. Habilita el desarrollo web full stack con la estabilidad, consistencia y productividad de .NET.

¿Aún te quedas con ganas de conocer más? Echa un ojo a este otro link. ¡Y, Recuerda que “Razor” y “Razor Pages”  son cosas diferentes!

Ahora si, es el momento de ponerse con el código, y lo haremos partiendo de este Get Started, que resumo brevemente:

Requisitos/Herramientas

1.- Instalar NET Core 2.1 Preview 1 SDK.

2.- Instalar la última Preview de Visual Studio 2017 (15.7). ¡Tranquil@, puede convivir con tu Visual Studio sin ningún problema!

3.- Instalar ASP.NET Core Blazor Language Services extension o bien, directamente desde Visual Studio, configurar una nueva fuente “https://dotnet.myget.org/F/blazor-dev/vsix/” e instalar. Esta última alternativa nos permitirá disponer de las notificaciones de actualización en todo momento, dado que aun no se encuentra la extensión de Blazor en el Market Place.

image image

Un Nuevo Proyecto

1.- Crear un nuevo proyecto de tipo ASPNET Core Web Application:

image

2.- Seleccionar uno de los dos tipos de proyecto para Blazor: Blazor o Blazor (ASP.NET Core hosted).

 image

3.-  Actualizar referencias NuGet. Incluir una nueva fuente nos permitirá de las actualizaciones mucho más rápidamente.

image

4.- Compilar y ejecutar la solución. Si has optado por crear el proyecto de tipo Blazor (ASP.NET Core hosted), establece como “Startup Project” el proyecto con el sufijo “Server” , de los tres generados.

blazor-home

Nota: Por cada carpeta  Shared y Pages se generan namespaces, por lo que es recomenable que los nombres de los proyectos y  ensamblados coincidan con los namespaces. ¡Esto cosa de “Razor Pages”, que a diferencia de MVC, está basado en páginas en lugar de Controllers!

Además de los ejemplos del “Get Started” anterior, aquí dejo el código (Github) de mi proyecto Taskin, con el que podrás cacharrear cuanto quieras y seguir profundizando.

image

Un ejemplo, de donde es mejor usar Wasm, podemos verlo en este juego de demo o incluso, en algo más real, aquí.

Aspectos principales

  1. Layout. Cada fichero .cshtml con una instrucción “@implements ILayoutComponent” como primera línea, constituye un Layout. El Layout que usa cada aplicación se indica en el fichero _ViewImports.cshtml como: “@layout NOMBRE_LAYOUT
  2. Componentes. Cada página .cshtml es un componente Blazor. Para usar un componente, únicamente tenemos que escribirlo como si de un tag HTML se tratará. Ej.: “<Counter />”. Además,  éste puede tener parámetros (propiedades públicas) permitiendo así ser usados desde cualquier página u otro componente.
  3. App.cshtml. Utiliza el Router para realizar el enrutado de las peticiones (o requests) a componentes Blazor específicos. “<Router AppAssembly=typeof(Program).Assembly />”.
  4. Routing. La directiva @page, indica a cada componente que éste, es una página. Sin esta directiva, ningún componente podría ser enrutado pero si ser usado por cualquier otro componente o página, que hiciera este enrutamiento.
  5. Dependency Injection. La inyección se lleva a cabo usando “@inject”   Ej.:“@inject HttpClient Http”
  6. Componente principal (o Root).  El componente principal de la aplicación se especifica en el EntryPoint:  Program.Main, definido en Program.cs, que es donde se configuran los proveedores de servicios (o services providers) para la aplicacion.
  7. Index.html.  Html que determina donde se reenderizará el comonponente. En tiempo de compilación la etiqueta “<script type=”blazor-boot”></script>” es reemplazada por esta otra “<script src=”_framework/blazor.js” reload=”/_reload” linker enabled=”true” references=”ElGuerre.Taskin.Models.dll,Microsoft.AspNetCore.Blazor.Browser.dll,Microsoft.Extensions.DependencyInjection.dll, …” entrypoint=”ElGuerre.Taskin.Blazor.Program::Main” main=”ElGuerre.Taskin.Blazor.dll”></script>”, que maneja el inicio de la aplicación y el punto de entrada a la misma.
  8. Hosting with ASP.NET Core. Para la publicación en ASP,NET Core, el proyecto “Server” hace referencia al proyecto cliente haciendo uso de un middleware que permite que Blazor pueda estar disponible en los navegadores: “app.UseBlazor<Client.Program>();”

Y, tranquil@, Javascript no ha muerto. Aquí puedes ver una prueba de ello, Wasm también puede ser usado desde Angular gracias a Emscripten. Podemos ver una colección de ejemplos sobre su uso en este enlace: https://boyan.io/angular-wasm/.

Esto sólo ha sido el principio, Wasm está comenzando y Blazor también, ¡eso si, hay que seguir disfrutando de todo lo que trae y seguirá trayendo Blazor!

Referencias:

¡A new era/seasson coud be comming!
Saludos & do Wasm !
Juanlu

Nuevas Características C# 7.1

cs71_featuresBuenas,

Siguiendo con las características de C#, en este post continuaremos con nuestro Tour y veremos concretamente las de C# 7.1:

  • Async Main Method
  • Default Literal Expressions
  • Inferred Tuple Element Names

ver-github

¡Recordemos que aquí tenemos los links a todos los post sobre las características de C# desde su versión 6.0: https://elguerre.com/2017/12/14/y-ms-new-features-c-7-0-2-2/!

Enjoy your coding !
Juanlu

Referencia: https://docs.microsoft.com/es-es/dotnet/csharp/whats-new/csharp-7-1

Y más… New features C# 7.0 (2/2)

imageHola,

Una vez más, continuamos conociendo más características de C# 7.0. En esta ocasión, las cinco restantes a las que ya vimos en el post anterior. Las conoceremos a través del siguiente vídeo:

Ver vídeo Youtube

Local Functions
More expression-bodied members
throw Expresions
Generalized async return types
Numeric literal syntax improve-ments

Y como viene siendo habitual, aquí tenemos el código para “cacharrear” todo cuanto queramos sobre estas nuevas características.

Resultado de imagen de github logos resources

Referencias:
Características de C# 6.0 Parte 1
Características de C# 6.0 Parte 2
Características de C# 7.0 Parte 1
– https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-7

Saludos & happy coding in C#
Juanlu

Continuamos: New features C# 7.0 !

FeaturesCShar7-Parte1

Hola,

Continuamos conociendo características nuevas de C#, concretamente,  las de 7.0 y en profundidad, las cinco primeras de ellas en esta ocasión.

Como en post anteriores las veremos a través de un Video Tip (Video tutorial) que podemos encontrar en mi canal de Youtube: https://www.youtube.com/user/JuanluElguerre .

Imagen relacionada

En este pequeño vídeo mostraremos las siguientes características:

Out Variables
Tuples
Discards
Pattern Matching
ref Locals and Return

Resultado de imagen de github logos resourcesResultado de imagen de github logos resources


Referencias:
– Características de C# 6.0 Parte 1
– Características de C# 6.0 Parte 2
https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-7

Un saludo and happy improving your coding with C#
Juanlu

 

[Podcast] Buenas prácticas, testing, .NET Core y el estado de ciertas herramientas de desarrollo

podcast iconBuenas,

El pasado jueves 13, tuve la suerte de poder compartir nuevamente un Podcast junto con @ElBruno, quien una vez más me invitó a NTN, concretamente a la edición número 32.  En dicha sesión, hablamos de mis nuevas experiencias por el sur, del continuo uso de “tantas” nuevas tecnologías: .NET Core, Azure, Docker, etc. y, hablamos también de testing, la importancia de la calidad del código  y la integración con Sonarqube, así como de la integración continua.

Enlace al Podcast.

Algunas de las referencias/recursos, utilizados:

Ha sido un placer, como siempre, poder compartir mis experiencias. Espero que las disfrutéis.

Un saludo
Juanlu, ElGuerre