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" を参照するプロジェクトでは機能しません。
その他のリソース
ASP.NET Core