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

Вот пример:

{

  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",

  "title": "One or more validation errors occurred.",

  "status": 400,

  "traceId": "|7fb5e16a-4c8f23bbfc974667.",

  "errors": {

    "": [

      "A non-empty request body is required."

    ]

  }

}

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

services.AddControllers()

    .ConfigureApiBehaviorOptions(options =>

    {

        options.SuppressModelStateInvalidFilter = true;

    });

Выведение источников для привязки параметров

Механизм привязки моделей будет логически выводить источники извлечения значений на основе соглашений, описанных в табл. 30.1.

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

services.AddControllers().ConfigureApiBehaviorOptions(options =>

{

  // Подавить все выведение источников для привязки.

  options.SuppressInferBindingSourcesForParameters= true;

  // Подавить выведение типа содержимого multipart/form-data.

  options. SuppressConsumesConstraintForFormFileParameters = true;

});

Детальные сведения о проблемах для кодов состояния ошибок

 ASP.NET Core трансформирует результат ошибки (состояние 400 или выше) в результат с помощью типа ProblemDetails, который показан ниже:

public class ProblemDetails

{

  public string Type { get; set; }

  public string Title { get; set; }

  public int? Status { get; set; }

  public string Detail { get; set; }

  public string Instance { get; set; }

  public IDictionary<string, object> Extensions { get; }

    = new Dictionary<string, object>(StringComparer.Ordinal);

}

Чтобы протестировать это поведение, добавьте в 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.

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

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">

  <DocumentationFile>AutoLot.Api.xml</DocumentationFile>

  <NoWarn>1701;1702;1591;</NoWarn>

</PropertyGroup>

Настройка NoWarn с указанием 1591