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

  • Статья

ASP.NET Core предоставляет пакет анализаторов MVC, предназначенный для использования с проектами веб-API. Анализаторы работают с контроллерами, которые помечены с помощью ApiControllerAttribute. Кроме того, к ним применяются соглашения об использовании веб-API.

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

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

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

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

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

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

Документы OpenAPI содержат коды состояний и типы ответов, которые может возвращать действие. В ASP.NET Core MVC атрибуты, такие как ProducesResponseTypeAttribute и ProducesAttribute, используются для документирования действия. ASP.NET документация по веб-API 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 в виде предупреждения. Эту проблему можно устранить.

analyzer reporting a warning

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

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

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