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

 }

Чтобы протестировать это поведение, добавьте в ValuesController еще один метод:

 [HttpGet("error")]
 public IActionResult Error
 {
  return NotFound;
 }

Запустите приложение и посредством пользовательского интерфейса Swagger выполните новую конечную точку error. Результатом по-прежнему будет код состояния 404 (Not Found), но в теле ответа возвратится дополнительная информация. Ниже приведен пример ответа (ваше значение traceId будет другим):

 {
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "traceId": "00-9a609e7e05f46d4d82d5f897b90da624-a6484fb34a7d3a44-00"
 }

Такое поведение можно отключить через конфигурацию в методе ConfigureServices класса Startup:

 services.AddControllers
  .ConfigureApiBehaviorOptions(options =>
  {
   options.SuppressMapClientErrors = true;
  });

Когда поведение отключено, вызов конечной точки error возвращает код состояния 404 без какой-либо дополнительной информации.

Обновление настроек Swagger/OpenAPI

Продукт Swagger (также известный как OpenAPI) является стандартом с открытым кодом для документирования служб REST, основанных на API. Два главных варианта для добавления Swagger к API-интерфейсам ASP.NET Core — Swashbuckle и NSwag. Версия ASP.NET Core 5 теперь включает Swashbuckle в виде части шаблона нового проекта. Документация swagger.json, сгенерированная для AutoLot.Api, содержит информацию по сайту, по каждой конечной точке и по любым объектам, задействованным в конечных точках.

Пользовательский интерфейс 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
  {
   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<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.