Usar os analisadores da API Web

  • Artigo

ASP.NET Core fornece um pacote de analisadores MVC destinado ao uso com projetos de API Web. Os analisadores trabalham com controladores anotados com ApiControllerAttribute enquanto compilam nas convenções da API Web.

O pacote de analisadores o notifica sobre qualquer ação do controlador que:

  • Retorna um código de status não declarado.
  • Retorna um resultado de sucesso não declarado.
  • Documenta um código de status que não é retornado.
  • Inclui um marcar de validação de modelo explícito.

Referenciar o pacote do analisador

Os analisadores estão incluídos no SDK do .NET Core. Para habilitar o analisador no seu projeto, inclua a IncludeOpenAPIAnalyzers propriedade no arquivo de projeto:

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

Analisadores das convenções de API Web

Documentos de OpenAPI contêm códigos de status e tipos de resposta que uma ação pode retornar. No ASP.NET Core MVC, atributos como ProducesResponseTypeAttribute e ProducesAttribute são usados para documentar uma ação. A documentação da API da Web do ASP.NET Core com Swagger/OpenAPI apresenta mais detalhes sobre como documentar sua API da Web.

Um dos analisadores no pacote inspeciona controladores anotados com ApiControllerAttribute e identifica ações que não documentam totalmente as respostas. Considere o seguinte exemplo:

// 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);
}

A ação precedente documenta o tipo de retorno com êxito do HTTP 200, mas não documenta o código de status com falha do HTTP 404. O analisador relata a documentação ausente para o código de status HTTP 404 como um aviso. É fornecida uma opção para consertar o problema.

analyzer reporting a warning

Os analisadores exigem o Microsoft.NET.Sdk.Web

Os analisadores não funcionam com projetos de biblioteca ou projetos que fazem referência a Sdk="Microsoft.NET.Sdk" .

Recursos adicionais