Poprzednie

Następne

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

Ukończone

Twoja firma ma interfejs API o nazwie PrintFramerAPI, który oblicza koszt ramki na podstawie jej wymiarów. 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ć. Interfejs APIT to interfejs API platformy ASP.NET Core, dlatego decydujesz się na uwidocznienie dokumentacji interfejsu API za pośrednictwem interfejsu OpenAPI.

W tym ćwiczeniu udokumentowasz internetowy interfejs API platformy ASP.NET Core za pomocą interfejsu OpenAPI i wypróbujesz interfejs użytkownika struktury Swagger i pakiet Swashbuckle w rzeczywistym przykładzie. Najpierw utwórzmy projekt internetowego interfejsu API platformy ASP.NET Core.

Uwaga

W tym module używany jest interfejs wiersza polecenia platformy .NET (interfejs wiersza polecenia) i program Visual Studio Code na potrzeby programowania lokalnego. Po ukończeniu tego modułu możesz zastosować swoje pojęcia 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 i macOS).

Pobieranie przykładowego projektu internetowego interfejsu API do programu Visual Studio Code

1. Otwórz nowe wystąpienie programu Visual Studio Code.

2. Wybierz pozycję Widok, 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 git clone polecenie 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 wykonywania danych wyjściowych polecenia przejdź do: http://localhost:5000/api/priceframe/6/17

   Po przejściu na ten adres przeglądarka powinna wyświetlić komunikat 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, ujawniając dokumentację interfejsu API za pomocą interfejsu OpenAPI przy użyciu struktury Swashbuckle, wersji typu open source narzędzi struktury Swagger.

Dodawanie biblioteki Swagger do rozwiązania

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

   dotnet add package Swashbuckle.AspNetCore
   

2. Otwórz plik Startup.cs.

3. Na początku pliku dodaj kolejny wpis using:

   using Microsoft.OpenApi.Models;
   

4. Aby dodać generator struktury 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 pliku Startup.cs włącz oprogramowanie pośredniczące dla narzędzia Swagger UI, dodając wywołanie useSwagger i useSwaggerUI, jak pokazano w poniższym fragmencie 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.jsonadresu .

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

   

Kontynuuj