Ejercicio: Uso de Swashbuckle para crear un documento de OpenAPI

Completado

En este ejercicio, va a agregar Swagger y la interfaz de usuario de Swagger a una aplicación de API web de ASP.NET Core. Las herramientas de Swagger le ayudarán a crear el documento de OpenAPI que describe la API web.

Nota:

Para realizar este ejercicio, descargue el código fuente en el equipo local. Después de descargar el archivo, deberá descomprimirlo.

Descarga: Aplicación de API web de ASP.NET Core.

1. Seleccione el botón Descargar archivo sin procesar.
2. Descomprima el archivo exercise.zip.

Adición de las herramientas de Swagger

1. Abra Visual Studio y busque la aplicación de API web de ASP.NET Core.

   

2. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y seleccione Administrar paquetes NuGet.

   

3. En Administrador de paquetes NuGet, busque Swashbuckle.AspNetCore. Seleccione el paquete e instálelo.

   

   Ahora el paquete NuGet está instalado. Cierre la pestaña Administrador de paquetes NuGet.

Configuración de Swashbuckle para generar un documento de OpenAPI

1. Abra el archivo Startup.cs .

   

2. Agregue la directiva siguiente justo encima de la línea namespace InventoryManagement.ApiApp.

   /* === using directive BEGIN === */
   using Microsoft.OpenApi.Models;
   /* === using directive END === */
   

3. Reemplace todo el código dentro del método ConfigureServices(IServiceCollection) por el código siguiente:

       services.AddControllers();
   
       /* === SwaggerGen BEGIN === */
       services.AddSwaggerGen(c =>
       {
           c.SwaggerDoc("v1", new OpenApiInfo { Title = "Inventory Management", Version = "v1" });
       });
       /* === SwaggerGen END === */
   

4. En el método Configure(IApplicationBuilder, IWebHostEnvironment), busque la instrucción condicional if (env.IsDevelopment()) y reemplace todo lo que aparece antes de esa instrucción por el código siguiente:

       /* === SwaggerUI BEGIN === */
       app.UseSwagger(c =>
       {
           c.PreSerializeFilters.Add((swagger, httpReq) => {
               var server = new OpenApiServer() { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" };
               swagger.Servers = new List<OpenApiServer>() { server };
           });
       });
       app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "InventoryManagement.ApiApp v1"));
       /* === SwaggerUI END === */
   

   Nota:

   Es muy importante que los puntos de conexión de Swagger solo estén habilitados en el entorno de desarrollo. De lo contrario, podría exponer la API al público.

   Acaba de terminar de activar la característica de documentos de OpenAPI en la aplicación de API web de ASP.NET Core. Guarde el archivo Startup.cs. Los cambios tendrán un aspecto similar al de la siguiente captura de pantalla.

   

Generación del archivo de documento de OpenAPI

1. Seleccione el botón Depurar situado en la parte superior central de Visual Studio.

   

   Se abre automáticamente el explorador web y se muestra la página de la interfaz de usuario de Swagger.

   

   Es posible que vea la página de error 404. En este caso, escriba la dirección URL https://localhost:<port_number>/swagger en la barra de direcciones del explorador. En la captura de pantalla siguiente, la dirección URL es https://localhost:44371/swagger, por ejemplo.

   

2. Seleccione el vínculo para abrir la página del documento de OpenAPI.

   

3. El documento de OpenAPI se representa sobre la marcha.

   

La aplicación de API web de ASP.NET Core ya está lista para generar el documento de OpenAPI.