Use web API analyzers

ASP.NET Core 2.2 and later includes the Microsoft.AspNetCore.Mvc.Api.Analyzers NuGet package containing analyzers for web APIs. The analyzers work with controllers annotated with ApiControllerAttribute, while building on API conventions.

Package installation

Microsoft.AspNetCore.Mvc.Api.Analyzers can be added with one of the following approaches:

  • From the Package Manager Console window:

    • Go to View > Other Windows > Package Manager Console.

    • Navigate to the directory in which the ApiConventions.csproj file exists.

    • Execute the following command:

      Install-Package Microsoft.AspNetCore.Mvc.Api.Analyzers
      
  • From the Manage NuGet Packages dialog:

    • Right-click the project in Solution Explorer > Manage NuGet Packages.
    • Set the Package source to "nuget.org".
    • Enter "Microsoft.AspNetCore.Mvc.Api.Analyzers" in the search box.
    • Select the "Microsoft.AspNetCore.Mvc.Api.Analyzers" package from the Browse tab and click Install.

Analyzers for API conventions

OpenAPI documents contain status codes and response types that an action may return. In ASP.NET Core MVC, attributes such as ProducesResponseTypeAttribute and ProducesAttribute are used to document an action. ASP.NET Core Web API help pages with Swagger / OpenAPI goes into further detail on documenting your API.

One of the analyzers in the package inspects controllers annotated with ApiControllerAttribute and identifies actions that don't entirely document their responses. Consider the following example:

// 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);
}

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.

analyzer reporting a warning

Additional resources