使用 Web API 分析器
ASP.NET Core 2.2 和更高版本提供了用于 Web API 项目的 MVC 分析器包。 分析器使用带有 ApiControllerAttribute 批注的控制器，同时构建 Web API 约定。
分析器包会通知你执行以下操作的任何控制器操作：
- 返回未声明的状态代码。
- 返回未声明的成功结果。
- 记录不返回的状态代码。
- 包含显式模型验证检查。
引用分析器包
在 ASP.NET Core 3.0 或更高版本中，分析器随附在 .NET Core SDK 中。 若要在项目中启用分析器，请在项目文件中包含 IncludeOpenAPIAnalyzers 属性：
<PropertyGroup> <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> </PropertyGroup>
包安装
通过以下方法之一安装 Microsoft.AspNetCore.Mvc.Api.Analyzers NuGet 包：
-
Visual Studio
从“程序包管理器控制台” 窗口：
转到“视图”>“其他窗口”>“包管理器控制台” 。
导航到 ApiConventions.csproj 文件所在的目录 。
请执行以下命令：
Install-Package Microsoft.AspNetCore.Mvc.Api.Analyzers
-
Visual Studio for Mac
- 在“Solution Pad”>“添加包...”中右键单击“包”文件夹 。
- 将“添加包”窗口的“源”下拉列表设置为“nuget.org” 。
- 在搜索框中输入“Microsoft.AspNetCore.Mvc.Api.Analyzers”。
- 从结果窗格中选择“Microsoft.AspNetCore.Mvc.Api.Analyzers”包，然后单击“添加包” 。
-
Visual Studio Code
从“集成终端” 中运行以下命令：
dotnet add ApiConventions.csproj package Microsoft.AspNetCore.Mvc.Api.Analyzers
-
.NET Core CLI
运行下面的命令：
dotnet add ApiConventions.csproj package Microsoft.AspNetCore.Mvc.Api.Analyzers
Web API 约定的分析器
OpenAPI 文档包含操作可能返回的状态代码和响应类型。 在 ASP.NET Core MVC 中，ProducesResponseTypeAttribute 和 ProducesAttribute 等属性用于记录操作。 带有 Swagger/OpenAPI 的 ASP.NET Core Web API 帮助页 进一步介绍有关记录 Web API 的详细信息。
包中的其中一个分析器检查使用 ApiControllerAttribute 进行批注的控制器，并标识不完全记录其响应的操作。 请看下面的示例：
// 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 失败状态代码。 分析器将 HTTP 404 状态代码的缺失文档报告为警告。 提供了修复此问题的选项。
