Web API アナライザーを使用する

2025-07-30

ASP.NET Core には、Web API プロジェクトで使用するための MVC アナライザーパッケージが用意されています。アナライザーは、ApiControllerAttributeに基づいて構築しながら、で注釈が付けられたコントローラーで動作します。

アナライザーパッケージは、次のようなコントローラーアクションを通知します。

宣言されていない状態コードを返します。
宣言されていない成功の結果を返します。
返されない状態コードを文書化します。
明示的なモデル検証チェックが含まれています。

アナライザーパッケージを参照する

アナライザーは .NET SDK に含まれています。プロジェクトでアナライザーを有効にするには、プロジェクトファイルに IncludeOpenAPIAnalyzers プロパティを含めます。

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

Web API 規則のアナライザー

OpenAPI ドキュメントには、アクションが返す可能性がある状態コードと応答の種類が含まれています。 ASP.NET Core MVC では、 ProducesResponseTypeAttribute や ProducesAttribute などの属性を使用してアクションを文書化します。 Swagger/OpenAPI を使用したコア Web API ドキュメント ASP.NET、Web API の文書化について詳しく説明します。

パッケージ内のアナライザーの 1 つは、 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 状態コードの不足しているドキュメントを警告として報告します。問題を解決するオプションが用意されています。

警告を報告するアナライザー

アナライザーには Microsoft.NET.Sdk.Web が必要です

アナライザーは、 Sdk="Microsoft.NET.Sdk"を参照するライブラリプロジェクトやプロジェクトでは機能しません。

Additional resources