Documentar APIs con Swagger UI en .Net Core

Una de las tareas más importantes (y tediosas) en cualquier proyecto de software es elaborar una buena documentación. Un buen software podría ser infravalorado e infrautilizado si no existen documentos tales como manuales de usuario, descripciones técnicas o manuales de integración, que ayudan a cualquier persona involucrada a conocerlo y explotarlo.

Afortunadamente, cada vez existen más herramientas que nos ayudan a generar esa documentación. En el caso de las APIs desarrolladas utilizando la especificación OpenAPI disponemos de Swagger UI, una documentación visual auto generada a partir de nuestro código (utilizando los summary y firmas de los endpoints) que nos permite explorar y probar nuestra API. Integrar Swagger UI en nuestra API es extremadamente sencillo, comenzando por instalar el paquete NuGet Swashbuckle.AspNetCore.

Posteriormente, debemos habilitar que se gener el la documentación en XML a partir de nuestros summary. Para ello, nos vamos a las propiedades del proyecto, pestaña Build y activamos el check XML Documentation File.

Documentar APIs con Swagger UI en .Net Core

Posteriormente, debemos indicar que se debe generar y utilizar Swagger UI. Para ello, modificamos los métodos ConfigureServices y Configure de nuestra clase Startup.cs

 

public void ConfigureServices(IServiceCollection services)
{
   …
   services.AddSwaggerGen(c =>
  {
    c.SwaggerDoc(“v1.0”, new Info { Title = “My Weekly Diet API”, Version = “v1.0” });

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

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
   …
   app.UseSwaggerUI(c =>
  {
    c.SwaggerEndpoint(“/swagger/v1.0/swagger.json”, “MyWeeklyDiet API”);
    c.RoutePrefix = string.Empty;
  });
}

Finalmente, debemos decorar nuestros endpoints incluyendo la documentación

///
/// Returns all the ingredients
///

/// [HttpGet] [ProducesResponseType(typeof(ApiResult), StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status500InternalServerError)] [Produces(“application/json”)] public async Task<ActionResult> GetAll() { try { return new ApiResult(await _service.GetAll()); } catch(APIException ex) { return new ExceptionResult(ex); } catch(Exception ex) { return new ExceptionResult(ex); } } ///

/// Creates a new ingredient
///

///The ingredient to create /// [HttpPost] [ProducesResponseType(typeof(IngredientDTO), StatusCodes.Status201Created)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes.Status500InternalServerError)] [Produces(“application/json”)] public async Task Insert(IngredientDTO ingredient) { try { return new ApiResult(await _service.Insert(ingredient), StatusCodes.Status201Created); } catch (APIException ex) { return new ExceptionResult(ex); } catch (Exception ex) { return new ExceptionResult(ex); } }

Tras esto, al ejecutar nuestra API podremos visualizar Swagger UI, que mostrará los endpoints y su documentación, además de darnos la posibilidad de ejecutarlos directamente.

Publicamos la Azure Function desde visual studio y daremos de alta la cadena de conexión de la cuenta de almacenamiento en los connection strings del site.

Escrito por: Daniel Asensio, Technical de Backend en el equipo Bravent.