Инфраструктура .NET Core способна генерировать файл XML-документации для вашего проекта, исследуя методы на предмет наличия комментариев с тремя символами прямой косой черты (///). Чтобы включить такую функциональность в Visual Studio, щелкните правой кнопкой мыши на имени проекта AutoLot.Api и в контекстном меню выберите пункт Properties (Свойства). В открывшемся диалоговом окне Properties (Свойства) перейдите на вкладку Build (Сборка), отметьте флажок XML documentation file (Файл XML-документации) и укажите в качестве имени файла AutoLot.Api.xml. Кроме того, введите 1591 в текстовом поле Suppress warnings (Подавлять предупреждения), как показано на рис. 30.3.
Те же настройки можно вводить прямо в файле проекта. Ниже показан раздел PropertyGroup, который понадобится добавить:
Настройка NoWarn с указанием 1591 отключает выдачу предупреждений компилятором для методов, которые не имеют XML-комментариев.
На заметку! Предупреждения 1701 и 1702 являются пережитками ранних дней классической платформы .NET, которые обнажают компиляторы .NET Core. Чтобы взглянуть на процесс в действии, модифицируйте метод Get класса ValuesController следующим образом:
///
/// This is an example Get method returning JSON
///
///
///
/// [
/// "value1",
/// "value2"
/// ]
///
///
///
[HttpGet]
public IActionResult Get
{
return Ok(new string[] { "value1", "value2" });
}
Когда вы скомпилируете проект, в корневом каталоге проекта появится новый файл по имени AutoLot.Api.xml. Открыв его, вы увидите только что добавленные комментарии:
This is an example Get method returning JSON
[
"value1",
"value2"
]
На заметку! Если вы вводите три символа прямой косой черты перед определением класса или метода в Visual Studio, то среда создает начальную заглушку для XML-комментариев.
Далее необходимо объединить XML-комментарии со сгенерированным файлом swagger.json.
Сгенерированные 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-документации документирование может быть улучшено дополнительной конфигурацией конечных точек приложения.
Существуют дополнительные атрибуты, которые дополняют документацию Swagger. Чтобы применить их, начните с добавления показанных далее операторов using в файл ValuesController.cs:
using Microsoft.AspNetCore.Http;
using Swashbuckle.AspNetCore.Annotations;
