使用 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" 的程式庫專案或專案。

其他資源