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

ASP.NET Core には、Web API プロジェクトでの使用を目的とした MVC アナライザー パッケージが用意されています。 アナライザーは、Web API 規約の設定中に ApiControllerAttribute の注釈が付けられたコントローラーで動作します。

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

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

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

アナライザーは .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 状態コードの文書化の不備を警告として報告します。 問題を解決するためのオプションが提供されます。

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

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

その他のリソース

• Web API 規約を使用する
• Swagger/OpenAPI を使用する ASP.NET Core Web API のドキュメント
• ASP.NET Core を使って Web API を作成する