【译】使用Web API分析器

原文链接：传送门。

ASP.NET Core 2.2及后续版本提供了一个MVC分析器包，其目的是与API项目一起使用。

当与web API conventions 进行编译项目时，这个分析器与用ApiControllerAttribute标记的Controller一起使用。

如果控制器Action方法满足其中任意一条，那么分析器包便会通知你：

• 返回一个未声明的状态码
• 返回一个未声明的成功结果
• 标识一个没有返回的状态码
• 包含 一个显式的模型验证检查

引用分析器包

在ASP.NET Core 3.0及后续版本中，分析器包含在.NET Core SDK中。为了在你的项目中启用分析器，请在工程文件中包含IncludeOpenAPIAnalyzer属性。

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

适配Web API约定的分析器

OpenAPI包含了一个Action可能会返回的状态码以及响应类型。在ASP.NET Core MVC中，类似于 ProducesResponseTypeAttribute 和 ProducesAttribute 这样的特性被用来文档化一个Action。 ASP.NET Core web API documentation with Swagger / OpenAPI 有关于文档化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失败状态码。分析器会将对于404状态码的文档化丢失作为一个警告而报告出来。可以通过提示来修复此问题。

额外资源

• Use web API conventions
• ASP.NET Core web API documentation with Swagger / OpenAPI
• Create web APIs with ASP.NET Core