Язык программирования C#9 и платформа .NET5

Те же настройки можно вводить прямо в файле проекта. Ниже показан раздел PropertyGroup, который понадобится добавить:

 <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
  <DocumentationFile>AutoLot.Api.xml</DocumentationFile>
  <NoWarn>1701;1702;1591;</NoWarn>
 </PropertyGroup>

Настройка 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")
  }
  });
   var xmlFile = $"{Assembly.GetExecutingAssembly.GetName.Name}.xml";
   var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
   c.IncludeXmlComments(xmlPath);
 });

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

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

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

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

 using Microsoft.AspNetCore.Http;
 using Swashbuckle.AspNetCore.Annotations;

Атрибут Produces задает тип содержимого для конечной точки. Атрибут ProducesResponseType использует перечисление StatusCodes для указания возможного кода возврата для конечной точки. Модифицируйте метод Get класса ValuesController, чтобы установить application/json в качестве возвращаемого типа и сообщить о том, что результатом действия будет либо 200 (ОК), либо 400 (Bad Request):