Cvičení – povolení dokumentace OpenAPI v aplikaci ASP.NET Core Web API

Dokončeno

Vaše společnost používá rozhraní API s názvem PrintFramerAPI, které vypočítá cenu zarámování obrazu podle rozměrů rámu. Váš malý tým interně ví, jak používat rozhraní API. Pokud ale chcete rozhraní API přijmout třetími stranami, a proto ho potřebujete zdokumentovat. APIT je rozhraní API ASP.NET Core, takže se rozhodnete zpřístupnit dokumentaci k rozhraní API prostřednictvím OpenAPI.

V tomto cvičení zdokumentujete webové rozhraní API ASP.NET Core s OpenAPI a vyzkoušíte si Swagger UI a Swashbuckle v reálném příkladu. Nejdřív vytvoříte projekt webového rozhraní API ASP.NET Core.

Poznámka:

Tento modul používá rozhraní příkazového řádku .NET (rozhraní příkazového řádku) a Visual Studio Code pro místní vývoj. Po dokončení tohoto modulu můžete použít své koncepty pomocí vývojového prostředí, jako je Visual Studio (Windows), Visual Studio pro Mac (macOS) nebo pokračování ve vývoji pomocí editoru Visual Studio Code (Windows, Linux a macOS).

Stažení ukázkového projektu webového rozhraní API do editoru Visual Studio Code

1. Otevřete novou instanci nástroje Visual Studio Code.

2. Vyberte Zobrazit a pak vyberte Terminál , aby se otevřelo okno terminálu.

3. (Volitelné) Přejděte do adresáře, do kterého chcete soubory zkopírovat, například c:\MyProjects.

4. Pokud chcete naklonovat ukázkový projekt webového rozhraní API z GitHubu, spusťte v okně terminálu následující git clone příkaz.

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

5. Otevřete projekt v editoru Visual Studio Code pomocí následujícího příkazu terminálu.

   code -a .
   

První spuštění webového rozhraní API

1. V okně terminálu editoru Visual Studio Code zadejte následující příkaz:

   dotnet run
   

2. Po dokončení výstupu příkazu přejděte na: http://localhost:5000/api/priceframe/6/17

   Když na adresu přejdete v prohlížeči, měla by se zobrazit zpráva The cost of a 6x17 frame is $20.00.

Vzhledem k tomu, že jste rozhraní API vytvořili, znali jste jeho tvar, ale externí vývojář, který chce toto rozhraní API využívat, by nebyl tak šťastný. Těmto vývojářům můžete pomoct zveřejněním dokumentace k rozhraní API pomocí OpenAPI pomocí Swashbuckle, opensourcové verze nástrojů Swagger.

Přidání knihovny Swaggeru do řešení

1. Spuštěním dotnet add package příkazu přidejte do projektu Swashbuckle.

   dotnet add package Swashbuckle.AspNetCore
   

2. Otevřete soubor Startup.cs.

3. Na začátek souboru přidejte další položku using:

   using Microsoft.OpenApi.Models;
   

4. Pokud chcete do kolekce služeb přidat generátor Swagger, nahraďte metodu ConfigureServices(IServiceCollection services) následující implementací.

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

5. V metodě Configure v souboru Startup.cs povolte middleware pro Swagger UI tak, že přidáte useSwagger a useSwaggerUI, jak to demonstruje následující fragment kódu.

   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. Uložte změny v editoru.

7. Pokud chcete zobrazit změny, spusťte ASP.NET aplikaci místně. V okně terminálu v editoru Visual Studio Code zadejte následující příkaz:

   dotnet run
   

8. V prohlížeči přejděte na http://localhost:5000/swagger/v1/swagger.json.

   Odpověď v prohlížeči je tentokrát dokument popisující koncové body rozhraní API, podobně jako následující odpověď.