Documenta tu API utilizando Swagger y agiliza tu trabajo
La documentación no tiene porqué ser una carga, usa swagger y documenta de una forma sencilla y dinámica, te encantará genio 😊

No hace mucho tiempo cuando los desarrolladores escuchábamos la palabra documentación, lo primero que se nos venía a la mente eran pilas de hojas de cálculo, documentos, correos, cuadernillos y mucho trabajo manual, es entonces que esbozando un gesto de lamento decíamos pues, que se le va a hacer, hay que hacerlo, o mejore que lo haga el practicante!. Puede que hasta hoy suceda eso, en muchos centros de trabajo, pero no tiene porqué ser así, veamos cómo documentar los métodos y propiedades de un API.

De la forma en que se hacía antes, que era haciendo la documentación de forma manual, podemos extraer al menos dos grandes desventajas:

  • Al ser estática la documentación, tiende a quedar obsoleta, imaginemos por ejemplo que el método PagarBoleto ahora ya no devuelve un valor booleano, sino que ahora retorna un objeto de la clase Boleta, si no estamos atentos la documentación quedará obsoleta y esto puede tener consecuencias graves.
  • Requiere dedicación y tiempo, recursos que sin dudas son escasos y preciados, ya que como vimos en el punto anterior hay que estar atentos a cualquier cambio.

Entonces aquí es donde una herramienta llamada Swagger entra en escena, asumo que hay otras herramientas allá afuera, pero en esta ocasión me voy a concentrar en esta ya que es la que estoy utilizando actualmente y me parece muy buena, siéntete libre de comentar la herramienta que tu usas y le echamos un ojo.

Con que poniendo en postits que significa numHoras de la entidad trabajador ¿eh?

Conociendo la herramienta

La página oficial de swagger es https://swagger.io/ y ella misma lo define así: Swagger es el ecosistema de herramientas más utilizado para diseñar, desarrollar, testear y documentar API's con la especificación OpenAPI (OAS).

Como podemos notar, Swagger es mucho más que un documentador, pero aquí descubriremos un poco más sus funciones como documentador, a continuación describo algunas de sus características que me parecen más relevantes:

  • Es dinámico, si tu API cambia, la documentación también lo hará
  • Te permite manejar varias versiones de API y cada una con su documentación
  • Te provee de toda una interfaz gráfica robusta de documentación sin que tengas que programarla
  • En la misma documentación te permite testear los métodos HTTP
  • Te genera mockups de los objetos json que necesitan tus métodos de tu API
  • Fácil integración con tu código, aquí integraremos Swagger con un API hecho con .Net Core

Empecemos a usar Swagger

Pues bien, manos a la obra cracks, lo que haremos será integrar swagger con un API hecho en .Net Core, esto será lo que deberás hacer en el proyecto que quieras documentar, haciéndole unos pequeños ajustes según tus necesidades:

El proyecto del API en .Net Core fue el que hicimos en la entrada anterior, aquí el link https://bravedeveloper.com/2021/07/20/entendiendo-los-web-api-con-net-core-y-entity-framework/, y aquí el repo en Github (en el commit 59a491d) para que lo descargues y le apliques Swagger. Te recomiendo que primero leas la entrada mencionada y la hagas tu mismo, luego la documentas 😉

Para que el proyecto o repo que bajaste funcione deberás configurar bien tu cadena de conexión la cual esta en el archivo appsettings.Development.json y luego ejecutar el comando update-database desde el package manager console, de forma que se ejecuten las migraciones hacia tu base de datos.

Instalando dependencias

Desde Nuget instalar:

  • Swashbuckle.AspNetCore

Configurar Startup.cs

En primer lugar debes asegurarte de activar el siguiente checkbox y configurar bien la ruta del archivo de configuración xml de Swagger.

Fíjate que la ruta sea la raiz del proyecto, en caso te hayas descargado mi repo de github actualiza la ruta sino te dará error de compilación o dejarán de funcionar algunas cosas en la documentación

Propiedades del proyecto

En todo proyecto de .Net Core existe una clase llamada Startup que es la que contiene las instrucciones de configuración de servicios y middlewares, pues vamos a agregar una lineas a su método ConfigureServices:

        public void ConfigureServices(IServiceCollection services)
        {
            ...
            //Configuraciones de Swagger
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);

            services.AddSwaggerGen(config =>
            {
                config.SwaggerDoc("v1",
                    new Microsoft.OpenApi.Models.OpenApiInfo() //Swashbuckle.AspNetCore.Swagger.info() se usa en versiones anteriores
                    {
                        Title = "Ejemplo de swagger",
                        Description = "Esta es una documentación de swagger, aquí tambien puede ir información necesaria para utilizar el Api, etc..."
                    }
                );
                config.IncludeXmlComments(xmlPath);//Configuramos los comentarios en los controladores
            });
        }

Y ahora configuramos el Middleware, es decir el método Configure:

		public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });

            //Configuración de middleware
            app.UseSwagger();
            app.UseSwaggerUI(config => 
                config.SwaggerEndpoint("/swagger/v1/swagger.json","API SWAGGER!")    
            );
        }

Configurando los controladores

Para utilizar la documentación se tiene que agregar data anotations, o una especie de comentarios (pero con tres barras) antes de cada controlador mediante el cual mediante nodos le indicaremos valores que queremos que aparezcan en la documentación, sin embargo Swagger por su parte agregará de forma automática también información de cada método, veamos por ejemplo el caso del controlador siguiente:

Escribiendo /// (tres barras inclinadas) se autocompletarán algunos campos básicos, inténtalo crack

		/// <summary>
        /// Este método trae todos los autores
        /// </summary>
        /// <returns>Puros autores</returns>
        /// <remarks>Este es un remark para información ampliada de autores de libros comunes y conocidos.</remarks>
        /// <response code="200">Todo bien eh</response>
        /// <response code="400">La liaste ah</response>        
        [HttpGet]        
        public async Task<ActionResult<List<Autor>>> Get()
        {
            return await context.Autor.Include(x=>x.Libros).ToListAsync();
        }

El resultado de esto es el siguiente:

Ahora abriré un método y resaltaré los campos que yo puse en el controlador, nota como te hace la vida más fácil documentando una descripción corta, una mas detallada y los responses:

imagen

Como habrás notado al pulsar "Try it out" podrás ejecutar los métodos en esta misma página, lo que haces por ejemplo con Postman, lo puedes hacer directamente desde aquí también 😊

En aquellos controladores que tengan parámetro de tipo primitivo (int, string, double) se nos creará textboxes:

En los parámetros de tipo complejo se nos creará un mockup de json con info de ejemplo para facilidad nuestra, veamos:

Configurando las entidades

De las dos entidades que tengo en el proyecto, configuraré una propiedad de la entidad Autor:

   public class Autor
    {
        /// <summary>
        /// Este es el identificador de un autor
        /// </summary>
        public int Id { get; set; }
        public string Nombre { get; set; }
        public List<Libro> Libros { get; set; } //propiedad de navegación
    }

Al agregar summary, le estoy diciendo a Swagger, muéstrame esta info en la documentación que orientará mejor al usuario y le dirá que significa este campo:

En conclusión...

Como has podido apreciar, Swagger te facilita bastante la documentación de tu API, ahora el equipo frontend tendrá siempre la documentación actualizada y se evitarán tener que estar cambiando a cada momento los archivos, o decir, ¡lo siento, me olvidé de decirte que ahora el json no devuelve un número sino una colección! y gracias a Swagger, quiero agradecer al buen Alberto Picazo quien me ayudó a entender más esta herramienta, te recomiendo visitar su canal de Youtube, y sigue investigando crack!

Comparte este contenido 😊

Un comentario en «Documenta tu API utilizando Swagger y agiliza tu trabajo»

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *