使用 Web API 分析器Use web API analyzers

ASP.NET Core 2.2 和更高版本提供了用于 Web API 项目的 MVC 分析器包。ASP.NET Core 2.2 and later provides an MVC analyzers package intended for use with web API projects. 分析器使用带有 ApiControllerAttribute 批注的控制器,同时构建 Web API 约定The analyzers work with controllers annotated with 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

在 ASP.NET Core 3.0 或更高版本中,分析器随附在 .NET Core SDK 中。In ASP.NET Core 3.0 or later, the analyzers are included in the .NET Core SDK. 若要在项目中启用分析器,请在项目文件中包含 IncludeOpenAPIAnalyzers 属性:To enable the analyzer in your project, include the IncludeOpenAPIAnalyzers property in the project file:

<PropertyGroup>
 <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>

包安装Package installation

通过以下方法之一安装 Microsoft.AspNetCore.Mvc.Api.Analyzers NuGet 包:Install the Microsoft.AspNetCore.Mvc.Api.Analyzers NuGet package with one of the following approaches:

从“程序包管理器控制台”窗口:From the Package Manager Console window:

  • 请参阅查看 > 其他 Windows > 程序包管理器控制台Go to View > Other Windows > Package Manager Console.

  • 导航到 ApiConventions.csproj 文件所在的目录**。Navigate to the directory in which the ApiConventions.csproj file exists.

  • 运行以下命令:Execute the following command:

    Install-Package Microsoft.AspNetCore.Mvc.Api.Analyzers
    

Web API 约定的分析器Analyzers for web API conventions

OpenAPI 文档包含操作可能返回的状态代码和响应类型。OpenAPI documents contain status codes and response types that an action may return. 在 ASP.NET Core MVC 中,ProducesResponseTypeAttributeProducesAttribute 等属性用于记录操作。In ASP.NET Core MVC, attributes such as ProducesResponseTypeAttribute and ProducesAttribute are used to document an action. 带有 Swagger/OpenAPI 的 ASP.NET Core Web API 帮助页 进一步介绍有关记录 Web API 的详细信息。带有 Swagger/OpenAPI 的 ASP.NET Core Web API 帮助页 goes into further detail on documenting your web API.

包中的其中一个分析器检查使用 ApiControllerAttribute 进行批注的控制器,并标识不完全记录其响应的操作。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);
}

上述操作记录了 HTTP 200 成功返回类型,但未记录 HTTP 404 失败状态代码。The preceding action documents the HTTP 200 success return type but doesn't document the HTTP 404 failure status code. 分析器将 HTTP 404 状态代码的缺失文档报告为警告。The analyzer reports the missing documentation for the HTTP 404 status code as a warning. 提供了修复此问题的选项。An option to fix the problem is provided.

报告警告的分析器

其他资源Additional resources