2.4 KiB
| title | author | description | monikerRange | ms.author | ms.custom | ms.date | uid |
|---|---|---|---|---|---|---|---|
| Use web API analyzers | tdykstra | Learn about the ASP.NET Core MVC web API analyzers package. | >= aspnetcore-3.1 | tdykstra | mvc | 09/05/2019 | web-api/advanced/analyzers |
Use web API analyzers
ASP.NET Core provides an MVC analyzers package intended for use with web API projects. The analyzers work with controllers annotated with xref:Microsoft.AspNetCore.Mvc.ApiControllerAttribute, while building on web API conventions.
The analyzers package notifies you of any controller action that:
- Returns an undeclared status code.
- Returns an undeclared success result.
- Documents a status code that isn't returned.
- Includes an explicit model validation check.
Reference the analyzer package
The analyzers are included in the .NET Core SDK. To enable the analyzer in your project, include the IncludeOpenAPIAnalyzers property in the project file:
<PropertyGroup>
<IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>
Analyzers for web API conventions
OpenAPI documents contain status codes and response types that an action may return. In ASP.NET Core MVC, attributes such as xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute and xref:Microsoft.AspNetCore.Mvc.ProducesAttribute are used to document an action. xref:tutorials/web-api-help-pages-using-swagger goes into further detail on documenting your web API.
One of the analyzers in the package inspects controllers annotated with xref:Microsoft.AspNetCore.Mvc.ApiControllerAttribute and identifies actions that don't entirely document their responses. Consider the following example:
The preceding action documents the HTTP 200 success return type but doesn't document the HTTP 404 failure status code. The analyzer reports the missing documentation for the HTTP 404 status code as a warning. An option to fix the problem is provided.
Analyzers require Microsoft.NET.Sdk.Web
Analyzers don't work with library projects or projects referencing Sdk="Microsoft.NET.Sdk".