Поделиться через

Использование анализаторов веб-API

ASP.NET Core предоставляет пакет анализаторов MVC, предназначенный для использования с проектами веб-API. Анализаторы работают с контроллерами, аннотированными с , и при этом основываются на конвенциях веб-API .

Пакет анализаторов уведомляет вас о любых действиях контроллера, которые:

  • Возвращает необъявленный код состояния.
  • Возвращает результат успешного выполнения, который не был объявлен.
  • Документирует код состояния, который не возвращается.
  • Включает явную проверку модели.

Ссылка на пакет анализатора

Анализаторы включены в пакет SDK для .NET. Чтобы включить анализатор в проекте, включите IncludeOpenAPIAnalyzers свойство в файл проекта:

<PropertyGroup>
 <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>

Анализаторы соглашений для веб-API

Документы OpenAPI содержат коды состояния и типы ответов, которые могут возвращать действие. В ASP.NET Core MVC атрибуты, такие как ProducesResponseTypeAttribute и ProducesAttribute используются для документирования действия. Документация веб-API ASP.NET Core с помощью Swagger / OpenAPI более подробно рассматривает документирование вашего веб-API.

Один из анализаторов пакета проверяет контроллеры, аннотированные с помощью ApiControllerAttribute, и идентифицирует действия, которые не полностью документируют свои ответы. Рассмотрим следующий пример:

// GET api/contacts/{guid}
[HttpGet("{id}", Name = "GetById")]
[ProducesResponseType(typeof(Contact), StatusCodes.Status200OK)]
public IActionResult Get(string id)
{
    var contact = _contacts.Get(id);

    if (contact == null)
    {
        return NotFound();
    }

    return Ok(contact);
}

Предыдущее действие документирует тип возвращаемого значения успешности HTTP 200, но не документирует код состояния сбоя HTTP 404. Анализатор сообщает недостающую документацию по коду состояния HTTP 404 в виде предупреждения. Предоставляется возможность устранить проблему.

анализатор, сообщающий предупреждение

Для анализаторов требуется Microsoft.NET.Sdk.Web

Анализаторы не работают с проектами библиотеки или проектами, ссылающимися Sdk="Microsoft.NET.Sdk"на нее.

Дополнительные ресурсы

  • Last updated on