Esercizio - Abilitare la documentazione di OpenAPI in un'app per le API Web ASP.NET Core

• 8 minuti

L'azienda ha un'API denominata PrintFramerAPI che calcola il costo di una cornice in base alle dimensioni. Il team interno all'azienda, composto da poche persone, sa come usare l'API, Tuttavia, per avere l'API adottata da terze parti e quindi guidare l'azienda, è necessario documentarla. APIT è un'API core ASP.NET, quindi si decide di esporre la documentazione dell'API tramite OpenAPI.

In questo esercizio si documenta un'API Web ASP.NET Core con OpenAPI e si prova l'interfaccia utente di Swagger e Swashbuckle in un esempio reale. Per prima cosa è necessario creare un progetto per l'API Web di ASP.NET Core.

Scaricare il progetto API Web di esempio per Visual Studio Code

1. Aprire una nuova istanza di Visual Studio Code.

2. Selezionare Visualizza e quindi Terminale per aprire la finestra del terminale.

3. (Facoltativo) Passare a una directory in cui copiare i file, ad esempio c:\MyProjects.

4. Per clonare il progetto API Web di esempio da GitHub, eseguire il comando git clone seguente nella finestra del terminale.

   git clone https://github.com/MicrosoftDocs/mslearn-improve-api-developer-experience-with-swagger && cd mslearn-improve-api-developer-experience-with-swagger/PrintFramerAPI
   

5. Aprire il progetto in Visual Studio Code con il comando del terminale seguente.

   code -a .
   

Eseguire l'API Web per la prima volta

1. Nel finestra del terminale di Visual Studio Code immettere il comando seguente:

   dotnet run
   

2. Al termine dell'output del comando, passare a: http://localhost:5000/api/priceframe/6/17

   Quando si inserisce l'indirizzo nel browser deve essere visualizzato il messaggio The cost of a 6x17 frame is $20.00.

Poiché l'API è stata creata, si conosce la forma, ma uno sviluppatore esterno che vuole usare questa API non sarebbe così fortunato. È possibile aiutare gli sviluppatori esponendo una documentazione sull'API con l'aiuto di OpenAPI usando Swashbuckle, una versione open source degli strumenti Swagger.

Aggiungere la raccolta Swagger alla soluzione

1. Aggiungere Swashbuckle al progetto eseguendo il comando dotnet add package.

   dotnet add package Swashbuckle.AspNetCore
   

2. Aprire il file Startup.cs.

3. Nella parte superiore del file aggiungere un'altra voce using:

   using Microsoft.OpenApi.Models;
   

4. Per aggiungere il generatore di Swagger alla raccolta di servizi, sostituire il metodo ConfigureServices(IServiceCollection services) con l'implementazione seguente.

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddControllers();
   
       services.AddSwaggerGen(c =>
       {
           c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
       });
   }
   

5. Nel metodo Configure in Startup.cs abilitare il middleware per l'interfaccia utente di Swagger aggiungendo useSwagger e useSwaggerUI come illustrato nel frammento di codice seguente.

   public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
   {
       if (env.IsDevelopment())
       {
           app.UseSwagger();
           app.UseSwaggerUI(c =>
           {
               c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
           });
   
           app.UseDeveloperExceptionPage();
       }
   
       app.UseHttpsRedirection();
   
       app.UseRouting();
   
       app.UseAuthorization();
   
       app.UseEndpoints(endpoints =>
       {
           endpoints.MapControllers();
       }); 
   }
   

6. Salvare le modifiche nell'editor.

7. Per visualizzare le modifiche, eseguire l'applicazione ASP.NET in locale. Digitare il comando seguente nella finestra del terminale in Visual Studio Code:

   dotnet run
   

8. In un browser passare a http://localhost:5000/swagger/v1/swagger.json.

   La risposta nel browser questa volta è un documento che descrive gli endpoint dell'API, simile alla seguente.