Introducción
La plataforma de Azure provee un vasto set de capacidades dentro de un modelo de Plataforma como servicio (PaaS) para alojar aplicaciones web y servicios. La plataforma es capaz de ofrecer algo más que solo alojar para ejecutar la lógica en sus aplicaciones; esta también incluye una serie de robustos mecanismos para gestionar todos los aspectos acerca del ciclo de vida de su aplicación web como servicios web respectivamente.
Azure App Services incluye un numero de características para gestionar sus aplicaciones web y servicios incluyendo Web Apps, Logic Apps, Mobile Apps y API Apps. De esta manera hacemos introducción para explicar mediante este articulo con un breve ejemplo el uso de estas características para alojar en este caso específico una web API RESTful de manera muy sencilla y en adición a una documentación robusta y dinámica.
Estas características claves son de primordial importancia para la creación de aplicaciones web modernas a través de la nube de Azure como (PaaS).
Cuando usted está en el proceso de diseño de una arquitectura de software basada en una aplicación web, una de las capas que necesitara implementar es una API lo cual permite que las capas de su arquitectura puedan comunicarse con cada una de las demás. Independientemente de la arquitectura de su aplicación, esta es una buena oportunidad para que implemente una API RESTful para que dicha intercomunicación suceda con su respectiva documentación para el uso de su API.
Luego de leer este articulo usted podrá:
- Crear una aplicación API RESTful sobre Azure App service.
- Crear una documentación bien estructurada para la API utilizando herramientas de código abierto.
Crear una aplicación API con Azure App Service es un poco similar a crear una aplicación web normal desplegada como un App service. Usted podrá tener las mismas opciones disponibles para su aplicación API que usted tiene para una aplicación web normal.
Crear e implementar una aplicación API
Para crear una aplicación API RESTful en Azure App Service existen muchas formas, las maneras más comunes son ya sea mediante el portal de Azure o directamente desde Visual Studio, en este caso vamos a realizar el ejemplo desde Visual Studio 2019:
- Ejecute Visual Studio 2019 y seleccione en la opción Archivo > Nuevo > Proyecto.
- En la ventana emergente de Nuevo Proyecto, seleccione ASP.NET Web Application (.Net Framework) dentro de la categoría de Cloud y haga clic en Siguiente.
- En la ventana emergente de configuración del Nuevo Proyecto, escriba el nombre del proyecto, en la ubicación física en el disco seleccione el tipo de framework .NET a utilizar y luego haga clic en Crear.
- Seleccione la plantilla de Web API en la ventana emergente de configuración de nuevo proyecto y luego haga clic en Crear.
De esta manera Visual Studio crea un nuevo proyecto web API con la siguiente estructura de archivos en el árbol de archivos en el explorador de la solución:
Generar la documentación automática de la API usando Swashbuckle
Swashbuckle es un framework de código abierto muy popular que consiste en un gran ecosistema de herramientas que funcionan para diseñar, construir, documentar, y consumir su RESTful API, lo que lo vuelve la alternativa ideal para crear la documentación de la API de manera más automatizada, el paquete de NuGet está muy bien documentado así que pueden revisar la documentación para más detalles accediendo al proyecto GitHub accediendo al final del artículo.
Swashbuckle se proporciona a través de un conjunto de paquetes de NuGet: Swashbuckle y Swashbuckle Core. A continuación, siga estos pasos para agregar Swashbuckle a su proyecto de API:
- Instale el paquete de NuGet, lo cual incluye Swashbuckle.Core como una dependencia al momento de instalar usando el siguiente comando desde la consola de paquetes de Nuget:
Install-Package Swashbuckle
- El paquete de NuGet también instala un archivo de arranque inicial o bootstrapper (App_Start/SwaggerConfig.cs) lo cual habilita las rutas de Swagger al iniciar la aplicación API usando WebActivatorEx. Usted también puede configurar las opciones de Swashbuckle modificando el método de extensión GlobalConfiguration.Configuration.EnableSwagger en el archivo SwaggerConfig.cs. también puede excluir de su API las acciones que han sido marcadas con el decorativo de obsoletas agregando la siguiente configuración:
public class SwaggerConfig
{
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
...
...
//Set this flag to omit schema property descriptions for any type properties decorated with the Obsolete attribute
c.IgnoreObsoleteProperties();
...
...
});
}
}
- Modifique las acciones de los controladores en su proyecto API para incluir el atributo swagger para ayudar al generador a construir los metadatos de swagger.
- Swashbuckle está ahora configurado para generar los metadatos Swagger para los endpoints de su API con una simple interfaz de usuario para explorar la metadata. Por ejemplo, el controlador que se lista puede producir la UI que se muestra bastando solo con escribir Swagger en la barra del navegador web seguido de la url de la aplicación web.
Publicar la API RESTful en Azure App Service
Hasta este punto ya tenemos el diseño de una API con lo básico para conectar con las demás capas de su proyecto, también contamos con una documentación que ya se genera de manera automática, aprovechando al máximo toda la metadata y definición de su API a través de las acciones de sus controladores, ya preparado lo anterior mencionado hasta este momento para implementar su aplicación API se necesita completar la publicación desde Visual Studio hacia Azure App Service para desplegar su proyecto API en la nube.
Siga estos pasos para desplegar su proyecto API desde Visual Studio:
- Haga clic derecho sobre el proyecto en el Visual Studio Solution Explorer y luego hacer clic en Publicar.
- En la ventana de dialogo de publicación, seleccione en App Service en la parte izquierda superior, luego Crear Nuevo, posteriormente hacer clic en publicar para ir a la configuración de App Service de Azure.
- La ventana cambiara y lo enviara a una configuración más específica donde primeramente debe de escribir el nombre de la aplicación a desplegar en Azure App Services, luego seleccione la suscripción a la cual está asociado en su portal de Azure.
- A continuación, se debe de especificar un grupo de recurso dentro de la nube de Azure al cual se va a asignar la aplicación web API como recurso de Azure App Service.
- En el caso de que no posea ningún recurso o quiera crear un nuevo recurso haga clic en nuevo nombre de grupo de recurso a crear.
- Este grupo de recurso por lo general asigna una capacidad de gasto calculado a través de un plan de hosting escalable con más o menos capacidades como lo son por ejemplo uso de RAM o número de procesadores necesarios para la ejecución del API, lo cual por defecto selecciona S1 (1 core, 1.75 GB RAM), en este caso le vamos a bajar escalabilidad del API para efectos de prueba y seleccionamos un plan de costos gratuito, este por ser compartido y además por ser un ambiente inicial de pruebas, cuando ya se quiera escalar más la aplicación o cambiar a un ambiente de más calidad y/o producción se puede optimizar a un plan adecuado para ejecutar de manera eficiente su proyecto API.
- Una vez configurado todo el entorno del proyecto API en Azure App Service, se crea un perfil de publicación en Visual Studio para que cada vez que quiera ejecutar un despliegue de su API con cambios nuevos simplemente le damos a ejecutar la publicación mediante el botón Publicar. Visual Studio procede a compilar e intentar subir todos los archivos del proyecto API hacia la nube de Azure mediante Azure App service, de esta manera ya puede acceder a su API a través de la internet.
- Cuando la publicación de su proyecto API esté finalizado, este abrirá en una nueva ventana de navegador donde se mostrará la página web inicial de publicación.
- Navegaremos hacia la documentación Swagger a través de la ruta /Swagger para ver los detalles de la documentación de la API, además para probar los métodos REST ya expuestos mediante la API. Por ejemplo, http://<SU-API-APP>.azurewebsites.net/swagger/
De esta manera ya podemos contar con una aplicación RESTful con una documentación bien estructurada de manera automatizada debidamente ejecutándose a través de la nube de Azure mediante Azure App Service.
Código fuente
https://github.com/hughfernandez/API-RESTfull-Demo-Doc-Swagger
Hugo Fernandez 