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

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")

      }

    });

});

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

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 

ApplicationDbContext context)

{

  if (env.IsDevelopment())

  {

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

    app.UseDeveloperExceptionPage();

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

    // app.UseSwagger();

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

    //                                         "AutoLot.Api v1"));

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

    if (Configuration.GetValue("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, который понадобится добавить:

  AutoLot.Api.xml

  1701;1702;1591;

Настройка NoWarn с указанием 1591 отключает выдачу предупреждений компилятором для методов, которые не имеют XML-комментариев.

На заметку! Предупреждения 1701 и 1702 являются пережитками ранних дней классической платформы .NET, которые обнажают компиляторы .NET Core. Чтобы взглянуть на процесс в действии, модифицируйте метод Get() класса ValuesController следующим образом:

///

/// This is an example Get method returning JSON

///

/// This is one of several examples for returning JSON:

///

/// [

///   "value1",

///   "value2"

/// ]

///

///

/// List of strings

[HttpGet]

public IActionResult Get()

{

  return Ok(new string[] { "value1", "value2" });

}

Когда вы скомпилируете проект, в корневом каталоге проекта появится новый файл по имени AutoLot.Api.xml. Открыв его, вы увидите только что добавленные комментарии:

 

    AutoLot.Api