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

Троелсен Эндрю

// app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json",

// "AutoLot.Api v1"));

// Инициализировать базу данных.

if (Configuration.GetValue<bool>("RebuildDataBase"))

{

SampleDataInitializer.ClearAndReseedDatabase(context);

}

}

// Включить промежуточное ПО для обслуживания сгенерированного

//

файла Swagger как конечной точки JSON.

app.UseSwagger;

// Включить промежуточное ПО для обслуживания пользовательского

// интерфейса Swagger (HTML, JS, CSS и т.д.), указывая конечную

// точку JSON для Swagger

app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json",

"AutoLot Service

v1"); });

...

}

В предыдущем коде используется

Swagger(app.UseSwagger)

и пользовательский интерфейс Swagger(

app.useSwaggerUI

). В нем также конфигурируется конечная точка для файла

swagger.json

.

Добавление файла XML-документации

Инфраструктура .NET Core способна генерировать файл XML-документации для вашего проекта, исследуя методы на предмет наличия комментариев с тремя символами прямой косой черты (

///

). Чтобы включить такую функциональность в Visual Studio, щелкните правой кнопкой мыши на имени проекта

AutoLot.Api

и в контекстном меню выберите пункт Properties (Свойства). В открывшемся диалоговом окне Properties (Свойства) перейдите на вкладку Build (Сборка), отметьте флажок XML documentation file (Файл XML-документации) и укажите в качестве имени файла

AutoLot.Api.xml

. Кроме того, введите 1591 в текстовом поле Suppress warnings (Подавлять предупреждения), как показано на рис. 30.3.

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

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;