Язык программирования C#9 и платформа .NET5 - Троелсен Эндрю
Настройка
NoWarn1591На заметку! Предупреждения 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.jsonusingStartup.csusing System.IO;using System.Reflection;Файл XML-документации добавляется в Swagger вызовом метода
IncludeXmlComments()AddSwaggerGen()ConfigureServices()StartupAddSwaggerGen()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. Чтобы применить их, начните с добавления показанных далее операторов
usingValuesController.csusing Microsoft.AspNetCore.Http;
