Uso de analizadores de API web

ASP.NET Core proporciona 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

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>

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. La documentación de la API web de ASP.NET Core con Swagger/OpenAPI trata más detalladamente cómo documentar la 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.

Los analizadores requiren Microsoft.NET.Sdk.Web.

Los analizadores no funcionan con proyectos de biblioteca o proyectos que hacen referencia a Sdk="Microsoft.NET.Sdk".

Recursos adicionales

• Uso de convenciones de API web
• Documentación de la API web de ASP.NET Core con Swagger/OpenAPI
• Creación de API web con ASP.NET Core