Cómo usar Swagger en ASP.Net Core

A menudo, querrá crear documentación para su API. Para crear esta documentación, puede aprovechar Swagger, una herramienta que se puede utilizar para proporcionar una representación de la interfaz de usuario de su API con facilidad. Una vez que haya generado la documentación de Swagger para su API, puede ver la firma de sus métodos de API e incluso probar sus métodos de API también.

Swashbuckle es un proyecto de código abierto para generar documentos Swagger. Este artículo presenta una discusión sobre cómo podemos aprovechar Swashbuckle para generar documentación interactiva para nuestra API RESTful.

Crear un proyecto ASP.Net Core

En primer lugar, creemos un proyecto ASP.Net Core en Visual Studio. Suponiendo que Visual Studio 2017 o Visual Studio 2019 esté instalado en su sistema, siga los pasos que se describen a continuación para crear un nuevo proyecto ASP.Net Core en Visual Studio.

  1. Inicie el IDE de Visual Studio.
  2. Haga clic en "Crear nuevo proyecto".
  3. En la ventana "Crear nuevo proyecto", seleccione "Aplicación web ASP.Net Core" de la lista de plantillas que se muestran.
  4. Haga clic en Siguiente. 
  5. En la ventana "Configure su nuevo proyecto" que se muestra a continuación, especifique el nombre y la ubicación del nuevo proyecto.
  6. Haga clic en Crear. 
  7. En la ventana "Crear nueva aplicación web ASP.Net Core", seleccione .Net Core como tiempo de ejecución y ASP.Net Core 2.2 (o posterior) de la lista desplegable en la parte superior.
  8. Seleccione "API" como plantilla de proyecto para crear un nuevo proyecto de API web ASP.Net Core. 
  9. Asegúrese de que las casillas de verificación "Habilitar compatibilidad con Docker" y "Configurar para HTTPS" no estén marcadas, ya que no usaremos esas funciones aquí.
  10. Asegúrese de que la autenticación esté configurada como "Sin autenticación", ya que tampoco usaremos autenticación.
  11. Haga clic en Crear.

Si sigue estos pasos, se creará un nuevo proyecto ASP.Net Core en Visual Studio. Usaremos este proyecto en las siguientes secciones de este artículo para examinar cómo podemos generar documentación Swagger para ValuesController.

Instale el middleware Swagger en ASP.Net Core

Si ha creado con éxito un proyecto ASP.Net Core, lo siguiente que debe hacer es agregar los paquetes NuGet necesarios a su proyecto. Para hacer esto, seleccione el proyecto en la ventana Explorador de soluciones, haga clic con el botón derecho y seleccione "Administrar paquetes NuGet ..." En la ventana Administrador de paquetes NuGet, busque el paquete Swashbuckle.AspNetCore e instálelo. Alternativamente, puede instalar el paquete a través de NuGet Package Manager Console como se muestra a continuación.

PM> Paquete de instalación Swashbuckle.AspNetCore

El paquete Swashbuckle.AspNetCore contiene las herramientas necesarias para generar documentos API para ASP.Net Core.

Configurar el middleware Swagger en ASP.Net Core

Para configurar Swagger, escriba el siguiente código en el método ConfigureServices. Observe cómo se utiliza el método de extensión AddSwaggerGen para especificar los metadatos del documento API.

services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", nueva información

                {

                    Versión = "v1",

                    Title = "Demostración de Swagger",

                    Description = "Demostración de Swagger para ValuesController",

                    TermsOfService = "Ninguno",

                    Contact = new Contact () {Name = "Joydip Kanjilal",

                    Correo electrónico = "[email protected]",

                    Url = "www.google.com"}

                });

            });

También debe habilitar Swagger UI en el método Configure como se muestra a continuación.

app.UseSwagger ();

app.UseSwaggerUI (c =>

{

   c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

});

Aquí está el código completo de la clase Startup para su referencia.

utilizando Microsoft.AspNetCore.Builder;

utilizando Microsoft.AspNetCore.Hosting;

utilizando Microsoft.AspNetCore.Mvc;

utilizando Microsoft.Extensions.Configuration;

utilizando Microsoft.Extensions.DependencyInjection;

usando Swashbuckle.AspNetCore.Swagger;

espacio de nombres SwaggerDemo

{

    inicio de clase pública

    {

        Inicio público (configuración de IConfiguration)

        {

            Configuración = configuración;

        }

        Configuración de IConfiguration pública {get; }

        public void ConfigureServices (servicios IServiceCollection)

        {

            services.AddMvc (). SetCompatibilityVersion

            (CompatibilityVersion.Version_2_2);   

            services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", nueva información

                {

                    Versión = "v1",

                    Title = "Demostración de Swagger",

                    Description = "Demostración de Swagger para ValuesController",

                    TermsOfService = "Ninguno",

                    Contact = new Contact () {Name = "Joydip Kanjilal",

                    Correo electrónico = "[email protected]",

                    Url = "www.google.com"

                }

                });

            });

        }

        Configure public void (aplicación IApplicationBuilder,

       IHostingEnvironment env)

        {

            if (env.IsDevelopment ())

            {

                app.UseDeveloperExceptionPage ();

            }

            app.UseMvc ();

            app.UseSwagger ();

            app.UseSwaggerUI (c =>

            {

                c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

            });

        }

    }

}

Esto es todo lo que necesita hacer para comenzar con Swagger.

Explore la interfaz de usuario Swagger de su aplicación ASP.Net Core

Ahora estamos listos para ejecutar la aplicación y explorar el punto final de Swagger. La IU de Swagger aparecerá como en la Figura 1 a continuación. Observe cómo Swagger usa diferentes colores para los verbos HTTP GET, PUT, POST y DELETE. Puede ejecutar cada uno de los puntos finales que se muestran en la Figura 1 directamente desde la interfaz de usuario de Swagger.

Cree comentarios XML en los métodos de acción de su controlador

Hasta aquí todo bien. En el documento Swagger generado anteriormente, no había comentarios XML. Si desea mostrar comentarios XML en el documento Swagger, simplemente escriba esos comentarios en los métodos de acción de su controlador.

Ahora escribamos comentarios para cada uno de los métodos de acción en ValuesController. Aquí está la versión actualizada de ValuesController con comentarios XML para cada uno de los métodos de acción.

  [Ruta ("api / [controlador]")]

    [ApiController]

    ValuesController de clase pública: ControllerBase

    {

        ///

        /// Obtener el método de acción sin ningún argumento

        ///

        ///

        [HttpGet]

        public ActionResult Obtener()

        {

            devolver nueva cadena [] {"valor1", "valor2"};

        }

        ///

        /// Obtener método de acción que acepta un número entero como argumento

        ///

        ///

        ///

        [HttpGet ("{id}")]

        public ActionResult Get (int id)

        {

            devolver "valor";

        }

        ///

        /// Método de acción posterior para agregar datos

        ///

        ///

        [HttpPost]

        Publicación vacía pública (valor de cadena [FromBody])

        {

        }

        ///

        /// Poner método de acción para modificar datos

        ///

        ///

        ///

        [HttpPut ("{id}")]

        public void Put (int id, [FromBody] valor de cadena)

        {

        }

        ///

        /// Eliminar método de acción

        ///

        ///

        [HttpDelete ("{id}")]

        public void Delete (int id)

        {

        }

    }

Activar comentarios XML en Swagger

Tenga en cuenta que Swagger no muestra comentarios XML de forma predeterminada. Debes activar esta función. Para hacer esto, haga clic con el botón derecho en Proyecto, seleccione Propiedades y luego navegue hasta la pestaña Generar. En la pestaña Crear, marque la opción "Archivo de documentación XML" para especificar la ubicación donde se creará el archivo de documentación XML.

También debe especificar que los comentarios XML deben incluirse al generar el documento Swagger escribiendo el siguiente código en el método ConfigureServices.

c.IncludeXmlComments (@ "D: \ Proyectos \\ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");

Y eso es todo lo que necesita hacer para activar los comentarios XML en Swagger.

Establezca la URL de inicio de la aplicación en Swagger UI

Puede cambiar la URL de inicio de su aplicación para especificar que la IU de Swagger se cargará cuando se inicie la aplicación. Para hacer esto, haga clic derecho en Proyecto y seleccione Propiedades. Luego navega a la pestaña Depurar. Por último, especifique el valor Launch Browser como swagger como se muestra en la Figura 2.

Cuando ejecute la aplicación nuevamente y navegue a la URL de Swagger, debería ver la IU de Swagger como se muestra en la Figura 3 a continuación. Tenga en cuenta los comentarios XML en cada uno de los métodos API esta vez.

Swashbuckle es una gran herramienta para generar documentos Swagger para su API. Lo más importante es que Swashbuckle es fácil de configurar y usar. Puedes hacer mucho más con Swagger de lo que hemos visto aquí. Puede personalizar la interfaz de usuario de Swagger utilizando hojas de estilo en cascada, mostrar valores de enumeración como valores de cadena y crear diferentes documentos de Swagger para diferentes versiones de su API, solo por nombrar algunos.