Uso de analizadores de API web
ASP.NET Core 2.2 y versiones posteriores proporcionan un paquete de analizadores de MVC diseñado para su uso con proyectos de API web. Los analizadores funcionan con los controladores anotados con ApiControllerAttribute y se compilan con convenciones de la API web.
El paquete de analizadores le informa de cualquier acción de controlador que:
- Devuelve un código de estado no declarado.
- Devuelve un resultado correcto no declarado.
- Documenta un código de estado que no se devuelve.
- Incluye una comprobación de validación del modelo explícita.
Referencia al paquete del analizador
En ASP.NET Core 3.0 o versiones posteriores, los analizadores se incluyen en el SDK de .NET Core. Para habilitar el analizador en el proyecto, incluya la propiedad IncludeOpenAPIAnalyzers en el archivo de proyecto:
<PropertyGroup>
<IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>
Instalación del paquete
Instale el paquete de NuGet Microsoft.AspNetCore.Mvc.Api.Analyzers con uno de los métodos siguientes:
En la ventana Consola del Administrador de paquetes:
Vaya a Ver > otras ventanas > Administrador de paquetes consola.
Vaya al directorio en el que esté el archivo ApiConventions.csproj.
Ejecute el comando siguiente:
Install-Package Microsoft.AspNetCore.Mvc.Api.Analyzers
Analizadores para las convenciones de API web
Los documentos de Open API contienen los códigos de estado y los tipos de respuesta que puede devolver una acción. En ASP.NET Core MVC, los atributos como ProducesResponseTypeAttribute y ProducesAttribute se usan para documentar una acción. Documentación de la API web de ASP.NET Core con Swagger/OpenAPI ofrece información más detallada sobre cómo documentar su API web.
Uno de los analizadores del paquete inspecciona los controladores anotados con ApiControllerAttribute e identifica las acciones que no documentan completamente sus respuestas. Considere el ejemplo siguiente:
// 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);
}
La acción anterior documenta el tipo de valor devuelto correcto HTTP 200, pero no documenta el código de estado de error HTTP 404. El analizador informa de la documentación que falta para el código de estado 404 de HTTP como una advertencia. Se proporciona una opción para corregir el problema.
