Ćwiczenie — włączanie dokumentacji interfejsu OpenAPI w aplikacji ASP.NET Core Web API

Ukończone

Twoja firma ma interfejs API o nazwie PrintFramerAPI, który oblicza koszt ramy obrazu na podstawie wymiarów ramki. Wewnętrznie mały zespół wie, jak używać interfejsu API. Jednak aby interfejs API został przyjęty przez inne firmy i w związku z tym prowadzić działalność biznesową, należy go udokumentować. API w ASP.NET Core, więc decydujesz się udostępnić dokumentację API za pomocą OpenAPI.

W tym ćwiczeniu udokumentujesz interfejs API ASP.NET Core Web za pomocą OpenAPI i wypróbujesz interfejs Swagger UI oraz Swashbuckle w rzeczywistym przykładzie. Najpierw utwórzmy projekt internetowego interfejsu API platformy ASP.NET Core.

Notatka

W tym module użyto interfejsu wiersza polecenia platformy .NET i programu Visual Studio Code na potrzeby programowania lokalnego. Po ukończeniu tego modułu możesz zastosować swoje koncepcje przy użyciu środowiska programistycznego, takiego jak Visual Studio (Windows), Visual Studio dla komputerów Mac (macOS) lub ciągłego programowania przy użyciu programu Visual Studio Code (Windows, Linux, & macOS).

Pobierz przykładowy projekt web API do programu Visual Studio Code

1. Otwórz nową instancję programu Visual Studio Code.

2. Wybierz pozycję View, a następnie wybierz pozycję Terminal, aby otworzyć okno terminalu.

3. (Opcjonalnie) Przejdź do katalogu, do którego chcesz skopiować pliki, na przykład c:\MyProjects.

4. Aby sklonować przykładowy projekt internetowego interfejsu API z usługi GitHub, uruchom następujące polecenie git clone w oknie terminalu.

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

5. Otwórz projekt w programie Visual Studio Code za pomocą następującego polecenia terminalu.

   code -a .
   

Uruchamianie internetowego interfejsu API po raz pierwszy

1. Wpisz następujące polecenie w oknie terminalu programu Visual Studio Code:

   dotnet run
   

2. Po zakończeniu wyświetlania wyników polecenia przejdź do: http://localhost:5000/api/priceframe/6/17

   Po przejściu do adresu w przeglądarce powinien on odpowiadać komunikatem The cost of a 6x17 frame is $20.00.

Ponieważ utworzono interfejs API, znasz jego kształt, ale zewnętrzny deweloper, który chce korzystać z tego interfejsu API, nie byłby tak szczęśliwy. Możesz pomóc tym deweloperom, udostępniając dokumentację API za pomocą OpenAPI przy użyciu Swashbuckle, wersji open source narzędzi Swagger.

Dodaj bibliotekę Swagger do rozwiązania

1. Dodaj pakiet Swashbuckle do projektu, uruchamiając polecenie dotnet add package.

   dotnet add package Swashbuckle.AspNetCore
   

2. Otwórz plik Startup.cs.

3. W górnej części pliku dodaj kolejny przy użyciu wpisu:

   using Microsoft.OpenApi.Models;
   

4. Aby dodać generator Swagger do kolekcji usług, zastąp metodę ConfigureServices(IServiceCollection services) następującą implementacją.

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

5. W metodzie Configure w Startup.cswłącz middleware dla Swagger UI, dodając useSwagger i useSwaggerUI, zgodnie z poniższym fragmentem kodu.

   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. Zapisz zmiany w edytorze.

7. Aby wyświetlić zmiany, uruchom lokalnie aplikację ASP.NET. Wpisz następujące polecenie w oknie terminalu w programie Visual Studio Code:

   dotnet run
   

8. W przeglądarce przejdź do http://localhost:5000/swagger/v1/swagger.json.

   Odpowiedź w przeglądarce tym razem jest dokumentem opisującym punkty końcowe interfejsu API, podobnie jak w poniższej odpowiedzi.