Implementando Swagger en Web APIs con .NET Core

Swagger es una de las mejores herramientas para documentar RESTful APIs mas populares del mundo. Con mas de 26 implementaciones para diferentes lenguajes de programación.

Swagger tiene una implementación para .NET Core bastante fácil de incorporar a nuestras proyectos.

El primer paso es instalar el paquete o nuget:

 <PackageReference Include="Swashbuckle.AspNetCore" Version="5.5.1" />

https://www.nuget.org/packages/Swashbuckle.AspNetCore.Swagger/

Luego hacemos la configuración del servicio en el método ConfigureServices

Puede agregar datos generales como versión, título, descripción, términos de uso, datos de contacto y licencia, todos estos son opcionales.

   services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = "ToDo API",
                    Description = "A simple example ASP.NET Core Web API",
                    TermsOfService = new Uri("https://example.com/terms"),
                    Contact = new OpenApiContact
                    {
                        Name = "Shayne Boyer",
                        Email = string.Empty,
                        Url = new Uri("https://twitter.com/spboyer"),
                    },
                    License = new OpenApiLicense
                    {
                        Name = "Use under LICX",
                        Url = new Uri("https://example.com/license"),
                    }
                });
            });

Luego agregamos los respectivos middlewares para generar el archivo Json y para generar la UI que nos va permitir visualizar los datos de una manera mas interactiva

  app.UseSwagger(c =>
  {
       c.SerializeAsV2 = true;
  });


// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
// specifying the Swagger JSON endpoint.
 app.UseSwaggerUI(c =>
 {
       c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
 });

Con esta configuración básica ya podemos acceder a la documentación que se va generar automáticamente utilizando la URL http://localhost:5050/swagger/index.html donde localhost:5050 es el nombre del sitio y el puerto de nuestro proyecto ejecutándose localmente.

Si queremos agregar información de los comentarios y descripciones de los métodos podemos agregar las siguientes lineas a la configuración de nuestro servicio:

 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
 c.IncludeXmlComments(xmlPath);

También, usando el atributo Produces podemos especificar el tipo de dato que retorna y con ProducesResponseType el tipo de respuesta Http, por ejemplo:

        /// <summary>
        /// Get a specific category by Id
        /// </summary>
        /// <param name="id">GUID Id for category</param>  
        [HttpGet("{id}")]
        [Produces("application/json")]
        [ProducesResponseType(StatusCodes.Status200OK)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        [ProducesResponseType(StatusCodes.Status400BadRequest)]
        public ActionResult<Category> Get(string id)
        {