Предыдущий

Следующая

Упражнение. Включение документации OpenAPI в приложении Веб-API ASP.NET Core

Завершено

У вашей организации есть API PrintFramerAPI, который вычисляет стоимость рамы на основе ее размеров. Ваша небольшая команда знает, как использовать API. Тем не менее, чтобы API был принят третьими лицами и, следовательно, управлять бизнесом, необходимо документировать его. APIT — это ASP.NET Core API, поэтому вы решили предоставить документацию по API через OpenAPI.

В этом упражнении вы задокументируйте веб-API ASP.NET Core с помощью OpenAPI и попробуйте использовать пользовательский интерфейс Swagger и Swashbuckle в реальном мире. Сначала необходимо создать проект веб-API ASP.NET Core.

Примечание.

В этом модуле используются .NET CLI (интерфейс командной строки) и Visual Studio Code для локальной разработки. По завершении этого модуля вы сможете применять его основные приемы в среде разработки Visual Studio (Windows), Visual Studio для Mac (macOS) или продолжить использование Visual Studio Code (Windows, Linux и macOS).

Скачайте пример проекта веб-API для Visual Studio Code.

1. Откройте новый экземпляр Visual Studio Code.

2. Выберите Вид и Терминал, чтобы открыть окно терминала.

3. (Необязательно.) Перейдите в каталог, в который требуется скопировать файлы, например c:\MyProjects.

4. Чтобы клонировать пример проекта веб-API из GitHub, в окне терминала выполните команду git clone.

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

5. Откройте проект в Visual Studio Code с помощью следующей команды терминала.

   code -a .
   

Первый запуск веб-API

1. В терминале Visual Studio Code введите следующую команду:

   dotnet run
   

2. После выполнения команды и получения выходных данных перейдите к http://localhost:5000/api/priceframe/6/17.

   При переходе по этому адресу в браузере вы должны получить следующее сообщение: The cost of a 6x17 frame is $20.00.

Так как вы создали API, вы знали свою форму, но внешний разработчик, который хочет использовать этот API, не будет так повезло. Вы можете помочь этим разработчикам, предоставив некоторую документацию по API с помощью OpenAPI с помощью Swashbuckle, версии средства Swagger с открытым исходным кодом.

Добавление в решение библиотеки Swagger

1. Добавьте Swashbuckle в наш проект, выполнив команду dotnet add package.

   dotnet add package Swashbuckle.AspNetCore
   

2. Откройте файл Startup.cs.

3. В верхней части файла добавьте другую запись using.

   using Microsoft.OpenApi.Models;
   

4. Чтобы добавить генератор Swagger в коллекцию служб, замените метод ConfigureServices(IServiceCollection services) следующей реализацией.

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

5. В методе Configure в файле Startup.cs следует включить промежуточное программное обеспечение для Swagger UI. Это можно сделать, добавив useSwagger и useSwaggerUI, как показано в следующем фрагменте кода.

   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. Сохраните изменения в редакторе.

7. Чтобы увидеть эти изменения, локально запустите приложение ASP.NET. Введите следующую команду в окне терминала в Visual Studio Code:

   dotnet run
   

8. В браузере перейдите на адрес http://localhost:5000/swagger/v1/swagger.json.

   В браузере будет получен ответ, который является описанием документации конечных точек API и может выглядеть следующим образом.

   

Продолжить