Swagger - Documentando un Web API 2 de ASP.NET Framework

En el anterior artículo de este blog Swagger - Cómo documentar servicios Web API de ASP.NET Core, vimos como integrar Swagger en un proyecto Web API RESTful de ASP.NET Core.

Para los que sigan utilizando el Full Framework de .NET, en esta ocasión realizaremos el mismo ejemplo del artículo anterior, pero esta vez integrando Swagger en un proyecto Web API 2 REST de ASP.NET Framework 4.6.x.

También veremos cómo habilitar la autenticación JWT en la interfaz de usuario (Swagger UI) para realizar las pruebas pertinentes a nuestros Web APIs.

 

Integrando Swagger en nuestro proyecto Web API de .NET Framework

En primer lugar, abriremos el proyecto Web API REST que ya creamos anteriormente en al artículo JSON Web Token - Seguridad en servicios Web API 2 de ASP.NET.

Desde la consola de administración de paquetes NuGet (Herramientas > Administrador de paquetes NuGet > Consola del Administrador de paquetes), instalaremos la herramienta Swashbuckle para ASP.NET Web API.

PM> Install-Package Swashbuckle

El paquete NuGet Swashbuckle, integrará la interfaz gráfica de Swager en nuestro proyecto, y además nos permitirá generar la documentación y especificaciones necesarias para los Web APIs definidos en nuestra aplicación.

Creando el archivo de documentación XML

Antes de comenzar a configurar Swagger, debemos habilitar en nuestro proyecto Web API la opción de generar archivo de configuración XML. Esto lo haremos situándonos en el proyecto, hacemos click con botón derecho, y seleccionamos la opción Compilación:

Este archivo XML generado, será utilizado por Swagger para aplicar a la interfaz de usuario las descripciones y comentarios que hayamos definido en nuestro proyecto.

Configurando Swagger 

Una vez instalado el paquete NuGet, observaremos que se ha creado el nuevo archivo SwaggerConfig.cs en la carpeta App_Start de nuestro proyecto. En el método Register() de esta clase (SwaggerConfig.cs), configuraremos las características de Swagger de la siguiente manera:

    public class SwaggerConfig
    {
        // OBTENEMOS EL PATH DEL ARCHIVO XML DE DOCUMENTACIÓN.
        protected static string GetXmlCommentsPath()
        {
            return Path.Combine(System.Web.HttpRuntime.AppDomainAppPath, "bin", "JsonWebTokensWebApi2.xml");
        }

        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration
                // HABILITAMOS SWAGGER EN EL PROYECTO.
                .EnableSwagger(c =>
                    {
                        // Use "SingleApiVersion" to describe a single version API. Swagger 2.0 includes an "Info" object to
                        // hold additional metadata for an API. Version and title are required but you can also provide
                        // additional fields by chaining methods off SingleApiVersion.
                        //
                        // DEFINIMOS LAS CARACTERÍSTICAS DEL WEB API.
                        c.SingleApiVersion("v1", "Título del Web API")
                            .Description("Aquí una descripción del Web API.")
                            .TermsOfService("Términos de servicio.")
                            .Contact(x => x
                                .Name("Rafael Acosta")
                                .Url("http://www.rafaelacosta.net/api-doc.pdf")
                                .Email("info@rafaelacosta.net"))
                            .License(x => x
                                .Name("Licencia")
                                .Url("http://www.rafaelacosta.net/license"));

                        // If you annotate Controllers and API Types with
                        // Xml comments (http://msdn.microsoft.com/en-us/library/b2s063f7(v=vs.110).aspx), you can incorporate
                        // those comments into the generated docs and UI. You can enable this by providing the path to one or
                        // more Xml comment files.
                        //
                        // HABILITAMOS EL ARCHIVO DE DOCUMENTACIÓN XML.
                        c.IncludeXmlComments(GetXmlCommentsPath());

                        // NOTE: You must also configure 'EnableApiKeySupport' below in the SwaggerUI section
                        //
                        // HABILITAMOS LA AUTENTICACIÓN JWT.
                        c.ApiKey("Authorization")
                        .Description("Introduce el Token JWT aquí.")
                        .Name("Bearer")
                        .In("header");

                        // If you want the output Swagger docs to be indented properly, enable the "PrettyPrint" option.
                        //
                        c.PrettyPrint();
                    })
                // HABILITAMOS LA INTERFAZ SWAGGER.
                .EnableSwaggerUi(c =>
                    {
                        // If your API supports ApiKey, you can override the default values.
                        // "apiKeyIn" can either be "query" or "header"
                        //
                        // HABILITAMOS LA AUTENTICACIÓN JWT EN LA INTERFAZ.
                        c.EnableApiKeySupport("Authorization", "header");

                        // Use the "DocumentTitle" option to change the Document title.
                        // Very helpful when you have multiple Swagger pages open, to tell them apart.
                        //
                        //c.DocumentTitle("My Swagger UI");

                    });
        }
    }

Accediendo a la interfaz gráfica - Swagger UI

Una vez realizada la configuración, ya podremos acceder a la interfaz gráfica de Swagger desde la dirección /swagger. El resultado inicial (sin documentación) sería el siguiente:

Como podemos ver, Swagger ha construido por nosotros una interfaz gráfica para pruebas con los dos Controladores de Web API que habíamos definido en nuestro proyecto, Login.cs y Pais.cs.

Además, se ha incluido en la interfaz el campo [ api_key ], que nos permitirá añadir un Token JWT a la cabecera de las peticiones HTTP que realicemos hacia los Controladores de Web API. Simplemente introduciremos el Token JWT precedido de la palabra Bearer ('B' mayúscula) y pulsamos el botón [ Explore ].

 

Documentando nuestros Web APIs de .NET Framework

A continuación, documentaremos las Acciones HTTP de nuestros Controladores de Web API.

Esto lo haremos mediante los comentarios de documentación XML que nos proporciona C#. Estos comentarios, se integran en nuestro código añadiendo tres barras diagonales /// al principio de las Acciones, y son utilizados por el compilador para generar el archivo de configuración XML que vimos anteriormente.

Un ejemplo para la Acción GET que obtiene un objeto (país) por su Id, sería el siguiente:

        // GET: api/Pais/5
        /// <summary>
        /// Obtiene un objeto por su Id.
        /// </summary>
        /// <remarks>
        /// Aquí una descripción mas larga si fuera necesario. Obtiene un objeto por su Id.
        /// </remarks>
        /// <param name="id">Id (GUID) del objeto.</param>
        /// <response code="401">Unauthorized. No se ha indicado o es incorrecto el Token JWT de acceso.</response>              
        /// <response code="200">OK. Devuelve el objeto solicitado.</response>        
        /// <response code="404">NotFound. No se ha encontrado el objeto solicitado.</response>
        [ResponseType(typeof(Pais))]
        public async Task<IHttpActionResult> GetPais(Guid id)
        {
            Pais pais = await db.Pais.FindAsync(id);
            if (pais == null)
            {
                return NotFound();
            }

            return Ok(pais);
        }

Volviendo a la interfaz Swagger, el resultado sería el siguiente:

 

Por último, para una Acción del tipo POST que crea un nuevo objeto en la base de datos, este sería un ejemplo:

        // POST: api/Pais
        /// <summary>
        /// Crea un nuevo objeto en la BD.
        /// </summary>
        /// <remarks>
        /// Aquí una descripción mas larga si fuera necesario. Crea un nuevo objeto en la BD.
        /// </remarks>
        /// <param name="pais">Objeto a crear en la BD.</param>
        /// <response code="401">Unauthorized. No se ha indicado o es incorrecto el Token JWT de acceso.</response>              
        /// <response code="201">Created. Objeto correctamente creado en la BD.</response>        
        /// <response code="400">BadRequest. No se ha creado el objeto en la BD. Formato del objeto incorrecto.</response>
        /// <response code="409">Conflict. El objeto a crear ya existe en la BD.</response>
        [ResponseType(typeof(Pais))]
        public async Task<IHttpActionResult> PostPais(Pais pais)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }

            db.Pais.Add(pais);

            try
            {
                await db.SaveChangesAsync();
            }
            catch (DbUpdateException)
            {
                if (PaisExists(pais.Id))
                {
                    return Conflict();
                }
                else
                {
                    throw;
                }
            }

            return CreatedAtRoute("DefaultApi", new { id = pais.Id }, pais);
        }

El resultado en la interfaz Swagger, quedaría así: