Esercizio: usare Swashbuckle per creare un documento OpenAPI

• 8 minuti

In questo esercizio si aggiungeranno Swagger e l'interfaccia utente di Swagger a un'applicazione API Web ASP.NET Core. Gli strumenti Swagger sono utili per creare il documento OpenAPI che descrive l'API Web.

1. Selezionare il pulsante Scarica file non elaborato.
2. Decomprimere il file exercise.zip.

Aggiungere gli strumenti Swagger

1. Aprire Visual Studio e individuare l'app API Web ASP.NET Core.

   

2. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto e scegliere il menu Gestisci pacchetti NuGet.

   

3. In Gestione pacchetti NuGet cercare Swashbuckle.AspNetCore. Selezionare il pacchetto e installarlo.

   

   Il pacchetto NuGet è stato installato. Chiudere la scheda Gestione pacchetti NuGet.

Configurare Swashbuckle affinché generi un documento OpenAPI

1. Apri il file Startup.cs.

   

2. Aggiungere la direttiva proprio sulla riga namespace InventoryManagement.ApiApp.

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

3. Sostituire tutto il codice nel metodo ConfigureServices(IServiceCollection) con il codice seguente:

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

4. Nel metodo Configure(IApplicationBuilder, IWebHostEnvironment) trovare l'istruzione condizionale if (env.IsDevelopment()) e sostituire tutti gli elementi precedenti a tale istruzione con il codice seguente:

       /* === 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

   È molto importante che gli endpoint Swagger siano abilitati solo nell'ambiente di sviluppo. In caso contrario, potrebbe esporre l'API al pubblico.

   L'attivazione della funzionalità per il documento OpenAPI nell'app API Web ASP.NET Core ora è stata completata. Salvare il file Startup.cs. Le modifiche potrebbero apparire come quelle nello screenshot seguente.

   

Generare il file del documento OpenAPI

1. Selezionare il pulsante di debug nella parte superiore centrale di Visual Studio.

   

   Il Web browser si apre automaticamente e mostra la pagina dell'interfaccia utente di Swagger.

   

   Potrebbe essere visualizzata la pagina di errore 404. In questo caso, immettere l'URL https://localhost:<port_number>/swagger nella barra degli indirizzi del browser. Nello screenshot seguente l'URL è https://localhost:44371/swagger, ad esempio.

   

2. Selezionare il collegamento per aprire la pagina del documento OpenAPI.

   

3. Il rendering del documento OpenAPI viene eseguito immediatamente.

   

L'app API Web ASP.NET Core è ora pronta per produrre il documento OpenAPI.