Usar analisadores de API Web

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 criam convenções de API 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 êxito não declarado.
• Documenta um código de status que não é retornado.
• Inclui uma verificação de validação de modelo explícita.

Referencie o pacote analisador

Os analisadores sã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 Web

Documentos 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. Documentação da API Web ASP.NET Core com Swagger/OpenAPI aprofunda-se em mais detalhes sobre a documentação da sua API Web.

Um dos analisadores no pacote inspeciona os controladores anotados ApiControllerAttribute e identifica ações que não documentam totalmente 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 sucesso 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.

Analisadores precisam de Microsoft.NET.Sdk.Web

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

Recursos adicionais

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