共用方式為


使用 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 中,如 ProducesResponseTypeAttributeProducesAttribute 等屬性會用以記載動作。 使用 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" 的程式庫專案或專案。

其他資源