Настройка
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 = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";</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;
