Usar analisadores de API da Web

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

O pacote de analisadores notifica você de 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 uma verificação explícita de validação do modelo.

Fazer referência ao pacote do analisador

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

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

Analisadores para convenções de API da Web

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

Um dos analisadores do pacote inspeciona controladores anotados com ApiControllerAttribute e identifica ações que não documentam totalmente as suas 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 anterior documenta o tipo de retorno de êxito HTTP 200, mas não documenta o código de status de falha HTTP 404. O analisador relata a documentação ausente para o código de status HTTP 404 como um aviso. Uma opção para corrigir o problema é fornecida.

Os analisadores requerem Microsoft.NET.Sdk.Web

Os analisadores não funcionam com projetos de biblioteca ou projetos que referenciam Sdk="Microsoft.NET.Sdk".

Recursos adicionais

• Usar convenções de API da Web
• Documentação da ASP.NET Core web API com Swagger / OpenAPI
• Crie APIs da Web com o ASP.NET Core