Упражнение. Настройка и расширение документации OpenAPI с помощью заметок и комментариев XML

  • 12 мин

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

  1. Чтобы проверить определение OpenAPI конечной точки API в пользовательском интерфейсе Swagger, перейдите в браузере к http://localhost:5000/swagger. При выборе метода Get должны отобразиться выходные данные, как показано ниже.

    Default Swagger UI for our API.

    Swagger UI предоставляет некоторую полезную информацию об API. Он отображает методы, которые можно вызвать (в нашем простом примере один из методов называется PriceFrame). Вы можете увидеть, что это операция HTTP Get, которая принимает два обязательных параметра с именем Height и Width. Чтобы увидеть вызов API в действии, можно выбрать "Попробовать", ввести значения высотыи ширины и выбрать "Выполнить".

    Пользователи API по-прежнему не имеют достаточно информации, чтобы знать ограничения метода PriceFrame . Предоставим им дополнительную информацию с помощью комментариев XML.

Добавление комментариев XML к API

  1. Вернитесь к экземпляру Visual Studio Code, который использовался в последнем упражнении.

  2. Если веб-API по-прежнему работает в последнем упражнении, нажмите клавиши CTRL+C в Windows или cmd+c на Mac, чтобы остановить его.

  3. Чтобы запустить документацию XML в проекте, обновите файл проекта PrintFramerAPI.csproj, добавьте тег GenerateDocumentationFile в существующую группу <PropertyGroup> и задайте для него значение true.

    <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

  4. Используйте инструкции и добавьте в файл Startup.cs следующее.

    using System.Reflection;
using System.IO;

  5. В Startup.cs сообщите Swashbuckle использовать XML-документацию, обновив вызов в ConfigureServicesAddSwaggerGen() .

     public void ConfigureServices(IServiceCollection services)
 {
     services.AddControllers();

     // Register the Swagger generator, defining 1 or more Swagger documents
     services.AddSwaggerGen(c =>
     {
         c.SwaggerDoc("v1", new OpenApiInfo
         {
             Version = "v1",
             Title = "PrintFramer API",
             Description = "Calculates the cost of a picture frame based on its dimensions.",
             TermsOfService = new Uri("https://go.microsoft.com/fwlink/?LinkID=206977"),
             Contact = new OpenApiContact
             {
                 Name = "Your name",
                 Email = string.Empty,
                 Url = new Uri("https://learn.microsoft.com/training")
             }
         });

         // Set the comments path for the Swagger JSON and UI.
         var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
         var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
         c.IncludeXmlComments(xmlPath);
     });
 }

    Чтобы определить имя файла XML для загрузки комментариев XML, в предыдущем коде используется отражение.

  6. В папке Controllers откройте PriceFrameController.cs. Добавьте следующий блок комментариев XML над атрибутом GetPrice HttpGet метода. Добавление комментариев с тройной косой чертой к действию улучшает Swagger UI. Это добавляет описание в заголовок раздела.

     /// <summary>
 /// Returns the price of a frame based on its dimensions.
 /// </summary>
 /// <param name="Height">The height of the frame.</param>
 /// <param name="Width">The width of the frame.</param>
 /// <returns>The price, in dollars, of the picture frame.</returns>
 /// <remarks> The API returns 'not valid' if the total length of frame material needed (the perimeter of the frame) is less than 20 inches and greater than 1000 inches.</remarks>
 [HttpGet("{Height}/{Width}")]
 public string GetPrice(string Height, string Width)
 {
     string result;
     result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
     return $"The cost of a {Height}x{Width} frame is ${result}";
 }

  7. Чтобы сохранить все изменения и убедиться, что они создаются локально, запустите в окне терминала Visual Studio Code следующую команду.

    dotnet build

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

    dotnet run

  9. Снова просмотрите пользовательский интерфейс Swagger http://localhost:5000/swagger, а затем ознакомьтесь со сведениями, добавленными в комментариях XML к документации OpenAPI.

    Swagger UI with the final documentation from XML comments for our API.

Добавление аннотации данных в API

Чтобы в Swagger можно было улучшать документацию OpenAPI, используйте атрибуты из пространства имен Microsoft.AspNetCore.Mvc.

  1. Если веб-API по-прежнему работает в последнем упражнении, нажмите клавиши CTRL+C в Windows или cmd+c на Mac, чтобы остановить его.

  2. В контроллер API PriceFrameController.cs необходимо добавить атрибут [Produces("text/plain")] над определением GetPrice. Он отображает сведения о том, что API GetPrice поддерживает тип содержимого ответа для text/plain.

    [HttpGet("{Height}/{Width}")]
[Produces("text/plain")]

    Этот тип содержимого выбирается в раскрывающемся списке в качестве значения по умолчанию для операций контроллера GET.

Добавление аннотаций Swashbuckle в API

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

Более надежным способом сообщить разработчикам типы ответов и коды ошибок являются следующие комментарии XML и аннотации данных. Средства Swashbuckle и Swagger используют эти значения, чтобы четко создать описание ожидаемых кодов http-ответов OpenAPI.

Также обновите конструктор фильтра глаголов HTTP, чтобы включить Name свойство и включить значение OpenAPI operationId .

  1. Добавьте следующую инструкцию using в файл PriceFrameController.cs .

    using Microsoft.AspNetCore.Http;

  2. В PriceFrameController.cs замените GetPrice приведенный ниже код и комментарий.

    /// <summary>
/// Returns the price of a frame based on its dimensions.
/// </summary>
/// <param name="Height">The height of the frame.</param>
/// <param name="Width">The width of the frame.</param>
/// <returns>The price, in dollars, of the picture frame.</returns>
/// <remarks>
/// Sample request:
///
///     Get /api/priceframe/5/10
///
/// </remarks>
/// <response code="200">Returns the cost of the frame in dollars.</response>
/// <response code="400">If the amount of frame material needed is less than 20 inches or greater than 1000 inches.</response>
[HttpGet("{Height}/{Width}", Name=nameof(GetPrice))]
[Produces("text/plain")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<string> GetPrice(string Height, string Width)
{
    string result;
    result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
    if (result == "not valid")
    {
        return BadRequest(result);
    }
    else
    {
        return Ok($"The cost of a {Height}x{Width} frame is ${result}");
    }
}

    После обновления кода будут выполнены следующие изменения.

    • Методы BadRequest() и Ok() используются для создания соответственно статусов BadRequest (400) и ОК, передавая результаты ответа в строку.
    • Комментарии XML описывают каждый код состояния, который может возвращать этот метод.
    • Атрибут HttpGet содержит Name свойство для выдачи параметра OpenAPI operationId .
    • Атрибуты ProducesResponseType перечисляют различные ответы, которые может возвращать действие. Как описано выше, эти атрибуты объединяются с комментариями XML, чтобы добавить описания, удобные для человека, к каждому ответу в сгенерированном Swagger.

  3. Перестройте веб-API с помощью следующей команды:

    dotnet build

  4. Запустите приложение ASP.NET с помощью следующей команды:

    dotnet run

  5. Снова просмотрите пользовательский интерфейс Swagger http://localhost:5000/swagger и ознакомьтесь со сведениями, полученными из этих заметок. Окончательный Swagger UI для API представлен на следующем рисунке.

    Swagger UI with more documentation from XML comments for our API.

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