Пользовательский интерфейс Swagger базируется на веб-интерфейсе и позволяет интерактивным образом исследовать конечные точки приложения, а также тестировать их (как делалось ранее в этой главе). Его можно расширить, добавляя документацию в сгенерированный файл
swagger.json
.
Обновление обращений к Swagger в классе Startup
Стандартный шаблон проекта API добавляет код для генерирования файла
swagger.json
в метод
ConfigureService()
класса
Startup
:
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "AutoLot.Api", Version = "v1" });
});
Первое изменение стандартного кода предусматривает добавление метаданных к
OpenApiInfo
. Модифицируйте вызов
AddSwaggerGen()
следующим образом, чтобы обновить заголовок и добавить описание и сведения о лицензии:
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1",
new OpenApiInfo
{
<b> Title = "AutoLot Service",</b>
Version = "v1",
<b> Description = "Service to support the AutoLot dealer site",</b>
<b> License = new OpenApiLicense</b>
<b> {</b>
<b> Name = "Skimedic Inc",</b>
<b> Url = new Uri("http://www.skimedic.com")</b>
<b> }</b>
});
});
Следующий шаг связан с переносом вызовов
UseSwagger()
и
UseSwaggerUI()
из блока, предназначенного только для среды разработки, в главный путь выполнения внутри метода
Configure()
. Кроме того, поменяйте заголовок
"AutoLot.Api vl"
на
"AutoLot Service vl"
.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env,
ApplicationDbContext context)
{
if (env.IsDevelopment())
{
// Если среда разработки, тогда отображать отладочную информацию.
app.UseDeveloperExceptionPage();
<b> // Первоначальный код:</b>
<b> // app.UseSwagger();</b>
<b> // app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json",</b>
<b> // "AutoLot.Api v1"));</b>
// Инициализировать базу данных.
if (Configuration.GetValue<bool>("RebuildDataBase"))
{
SampleDataInitializer.ClearAndReseedDatabase(context);
}
}
// Включить промежуточное ПО для обслуживания сгенерированного
// файла Swagger как конечной точки JSON.
<b> app.UseSwagger();</b>
// Включить промежуточное ПО для обслуживания пользовательского
// интерфейса Swagger (HTML, JS, CSS и т.д.), указывая конечную
// точку JSON для Swagger
<b> app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json",</b>
"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>
