Uso de Swagger en una ASP.NET Core 2 Web API (I)

El otro día, explicaba una forma de versionar nuestras Web APIs desarrolladas con ASP.NET Core 2 sin utilizar Microsoft.AspNetCore.Mvc.Versioning.

En esta ocasión, voy a indicar como sobre la base de aquel ejemplo, utilizar Swagger.

Swagger nos va a permitir generar documentación de nuestra Web API de forma fácil y sencilla.

Para ello, con la base del proyecto de versionado que mencionaba antes, voy a agregar el paquete NuGet de Swagger (Swashbuckle.AspNetCore).

Este paquete instalará a su vez otros paquetes necesarios para ejecutar Swagger de forma correcta.

Una vez hecho esto, voy a crear una clase nueva en la raiz del proyecto de nombre SwaggerConfiguration.cs con la siguiente información:

public class SwaggerConfiguration
{

    /// <summary>
    /// <para>Foo API v1</para>
    /// </summary>
    public const string EndpointDescription = "Foo API v1";

    /// <summary>
    /// <para>/swagger/v1/swagger.json</para>
    /// </summary>
    public const string EndpointUrl = "/swagger/v1/swagger.json";

    /// <summary>
    /// <para>Jorge Serrano</para>
    /// </summary>
    public const string ContactName = "Jorge Serrano";

    /// <summary>
    /// <para>http://geeks.ms/jorge/</para>
    /// </summary>
    public const string ContactUrl = "http://geeks.ms/jorge/";

    /// <summary>
    /// <para>v1</para>
    /// </summary>
    public const string DocNameV1 = "v1";

    /// <summary>
    /// <para>Foo API</para>
    /// </summary>
    public const string DocInfoTitle = "Foo API";

    /// <summary>
    /// <para>v1</para>
    /// </summary>
    public const string DocInfoVersion = "v1";

    /// <summary>
    /// <para>Foo Api - Sample Web API in ASP.NET Core 2</para>
    /// </summary>
    public const string DocInfoDescription = "Foo Api - Sample Web API in ASP.NET Core 2";

}

A continuación, iremos al fichero Startup.cs y agregaré las siguientes partes al código.

Dentro de public void ConfigureServices(IServiceCollection services) agregaré al final el siguiente código:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    // Register the Swagger generator, defining one or more Swagger documents
    services.AddSwaggerGen(swagger =>
    {
        var contact = new Contact() { Name = SwaggerConfiguration.ContactName, Url = SwaggerConfiguration.ContactUrl };
        swagger.SwaggerDoc(SwaggerConfiguration.DocNameV1,
                           new Info
                           {
                               Title = SwaggerConfiguration.DocInfoTitle,
                               Version = SwaggerConfiguration.DocInfoVersion,
                               Description = SwaggerConfiguration.DocInfoDescription,
                               Contact = contact
                           }
                            );
    });
}

Y al principio de public void Configure(IApplicationBuilder app, IHostingEnvironment env) agregaremos por su parte el siguiente código

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint(SwaggerConfiguration.EndpointUrl, SwaggerConfiguration.EndpointDescription);
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseMvc();
}

Una vez hecho esto, ejecutaremos nuevamente nuestra Web API.

Si ejecutamos la Url: http://[server]/swagger/v1/swagger.json obtendremos el JSON de las llamadas de nuestra Web API.

Ahora bien, si queremos verlo de forma legible, bastará con indicar la siguiente Url: http://[server]/swagger/

Aparecerá algo parecido a lo que se indica en la siguiente imagen:

Como podemos observar, en pantalla aparece información y configuración de nuestra Web API.

En otra entrada, indicaré como nutrir aún, más información a nuestra Web API.

¡Happy Coding!