Язык программирования C#9 и платформа .NET5 - Троелсен Эндрю

Настройка NoWarn с указанием 1591 отключает выдачу предупреждений компилятором для методов, которые не имеют XML-комментариев.

На заметку! Предупреждения 1701 и 1702 являются пережитками ранних дней классической платформы .NET, которые обнажают компиляторы .NET Core. Чтобы взглянуть на процесс в действии, модифицируйте метод Get() класса ValuesController следующим образом:

/// <summary>

/// This is an example Get method returning JSON

/// </summary>

/// <remarks>This is one of several examples for returning JSON:

/// <pre>

/// [

///   "value1",

///   "value2"

/// ]

/// </pre>

/// </remarks>

/// <returns>List of strings</returns>

[HttpGet]

public IActionResult Get()

{

  return Ok(new string[] { "value1", "value2" });

}

Когда вы скомпилируете проект, в корневом каталоге проекта появится новый файл по имени AutoLot.Api.xml. Открыв его, вы увидите только что добавленные комментарии:

<?xml version="1.0"?>

<doc>

  <assembly>

    <name>AutoLot.Api</name>

  </assembly>

  <members>

    <member name="M:AutoLot.Api.Controllers.ValuesController.Get">

      <summary>

        This is an example Get method returning JSON

      </summary>

    <remarks>This is one of several examples for returning JSON:

        <pre>

        [

          "value1",

          "value2"

        ]

        </pre>

      </remarks>

      <returns>List of strings</returns>    </member>

  </members>

</doc>

На заметку! Если вы вводите три символа прямой косой черты перед определением класса или метода в Visual Studio, то среда создает начальную заглушку для XML-комментариев.

Далее необходимо объединить XML-комментарии со сгенерированным файлом swagger.json.

Добавление XML-комментариев в процесс генерации Swagger

Сгенерированные XML-комментарии должны быть добавлены в процесс генерации swagger.json. Начните с добавления следующих операторов using в файл класса Startup.cs:

using System.IO;

using System.Reflection;

Файл XML-документации добавляется в Swagger вызовом метода IncludeXmlComments() внутри метода AddSwaggerGen(). Перейдите к методу ConfigureServices() класса Startup и модифицируйте метод AddSwaggerGen(), добавив файл XML-документации:

services.AddSwaggerGen(c =>

{

  c.SwaggerDoc("v1",

    new OpenApiInfo

    {

      Title = "AutoLot Service",

      Version = "v1",

      Description = "Service to support the AutoLot dealer site",

      License = new OpenApiLicense

      {

        Name = "Skimedic Inc",

        Url = new Uri("http://www.skimedic.com")

      }

    });

<b>    var xmlFile = $&quot;{Assembly.GetExecutingAssembly().GetName().Name}.xml&quot;;</b>

<b>    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);</b>

<b>    c.IncludeXmlComments(xmlPath);</b>

});

Запустите приложение и загляните в пользовательский интерфейс Swagger. Обратите внимание на XML-комментарии, интегрированные в пользовательский интерфейс Swagger (рис. 30.4).

Помимо XML-документации документирование может быть улучшено дополнительной конфигурацией конечных точек приложения.

Дополнительные возможности документирования для конечных точек API

Существуют дополнительные атрибуты, которые дополняют документацию Swagger. Чтобы применить их, начните с добавления показанных далее операторов using в файл ValuesController.cs:

using Microsoft.AspNetCore.Http;