使用 Web API 分析器

  • 项目

ASP.NET Core 提供了用于 Web API 项目的 MVC 分析器包。 分析器使用带有 ApiControllerAttribute 批注的控制器，同时构建 Web API 约定。

分析器包会通知你执行以下操作的任何控制器操作：

  • 返回未声明的状态代码。
  • 返回未声明的成功结果。
  • 记录不返回的状态代码。
  • 包含显式模型验证检查。

引用分析器包

分析器随附在 .NET Core SDK 中。 若要在项目中启用分析器，请在项目文件中包含 IncludeOpenAPIAnalyzers 属性：

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

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 状态代码的缺失文档报告为警告。 提供了修复此问题的选项。

analyzer reporting a warning

分析器需要 Microsoft.NET.Sdk.Web

分析器不适用于引用 Sdk="Microsoft.NET.Sdk" 的库项目或项目。

其他资源