Язык программирования C#9 и платформа .NET5 - Троелсен Эндрю

Пользовательский интерфейс 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 = &quot;AutoLot Service&quot;,</b>

      Version = &quot;v1&quot;,

<b>      Description = &quot;Service to support the AutoLot dealer site&quot;,</b>

<b>      License = new OpenApiLicense</b>

<b>      {</b>

<b>        Name = &quot;Skimedic Inc&quot;,</b>

<b>        Url = new Uri(&quot;http://www.skimedic.com&quot;)</b>

<b>      }</b>

    });

});

Следующий шаг связан с переносом вызовов UseSwagger() и UseSwaggerUI() из блока, предназначенного только для среды разработки, в главный путь выполнения внутри метода Configure(). Кроме того, поменяйте заголовок &quot;AutoLot.Api vl&quot; на &quot;AutoLot Service vl&quot;.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 

ApplicationDbContext context)

{

  if (env.IsDevelopment())

  {

    // Если среда разработки, тогда отображать отладочную информацию.

    app.UseDeveloperExceptionPage();

<b>    // Первоначальный код:</b>

<b>    // app.UseSwagger();</b>

<b>    // app.UseSwaggerUI(c =&gt; c.SwaggerEndpoint(&quot;/swagger/v1/swagger.json&quot;,</b>

<b>    //                                         &quot;AutoLot.Api v1&quot;));</b>

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

    if (Configuration.GetValue&lt;bool&gt;(&quot;RebuildDataBase&quot;))

    {

      SampleDataInitializer.ClearAndReseedDatabase(context);

    }

  }

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

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

<b>  app.UseSwagger();</b>

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

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

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

<b>  app.UseSwaggerUI(c =&gt; { c.SwaggerEndpoint(&quot;/swagger/v1/swagger.json&quot;,</b>

                                            &quot;AutoLot Service v1&quot;); });

  ...

}

В предыдущем коде используется 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, который понадобится добавить:

&lt;PropertyGroup Condition=&quot;'$(Configuration)|$(Platform)'=='Debug|AnyCPU'&quot;&gt;

  &lt;DocumentationFile&gt;AutoLot.Api.xml&lt;/DocumentationFile&gt;

  &lt;NoWarn&gt;1701;1702;1591;&lt;/NoWarn&gt;

&lt;/PropertyGroup&gt;