前へ

次へ

XML のコメントと注釈を使用して OpenAPI ドキュメントを充実させる

完了

Swagger UI を使用すると、ソース コードにアクセスする必要なく、API のリソースを操作して視覚化できます。 OpenAPI の仕様から API のグラフィカル表現が自動的に生成されるため、他の開発者はその API を使用するアプリの構築が簡単になります。

次の図に示すように、Swagger UI を使用すると操作とメソッドがわかりやすく視覚化されます。

Swagger UI では各操作を取り扱うことができ、試してみることもできます。

Swashbuckle と Swagger ツールによって API ドキュメントを自動作成すると、第三者が API のリソースについて理解するのに役立ちます。 しかし、さらに詳しい情報を提供したい場合はどうでしょうか。 API を初めて使用する場合は、できるだけ多くの情報が必要です。

XML コメント

XML コメントを含めることによって、自分のコードのドキュメントを作成できます。 通常、これらのコメントは、コメントを入れるコード ブロックの直前に配置します。

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

使用されている XML ノードを次に示します。

• summary: メソッド/クラス/フィールドの内容や機能についての概要です。
• 備考: メソッド、クラス、フィールドの詳細です。
• param: メソッドに対するパラメーターと、その内容です。
• returns: メソッドが返すものの説明です。

XML コメントを有効にすると、Swashbuckle ツールにより XML ドキュメント コメントが自動的に OpenAPI ドキュメントに組み込まれるので、Swagger UI でそれを表示できます。

データの注釈

データの注釈も同じです。 モデルに注釈を追加するだけで、Swagger がそれを組み込むように API ドキュメントを拡張します。

たとえば、コントローラーに次の注釈を追加します。

[Produces("application/json")]

... 追加された情報は以下のように Swagger UI 内に表示されます。

ヒント

API を記述するときに使用するべきいくつかのデータ注釈があります。

• 要求と応答に対して API で処理する content-types を指定します。 以下の属性は、API が両方向で application/json のコンテンツ タイプのみを使用することを指定します。

  [Produces("application/json")]
  [Consumes("application/json")]
  

• 呼び出し元のクライアントに返される可能性がある HTTP 応答コードを特定します。 次の属性は、404 Not Found を返す API を示します。

  [ProducesResponseType(StatusCodes.Status404NotFound)]
  

  API は、標準の応答コード セットを生成する場合がありますが、その場合は、次の属性を使用して、それぞれを個別に指定する代わりに 200、400、および 404 を指定できます。 詳細については、Web API 規則の使用に関するページを参照してください。

  [ApiConventionMethod(typeof(DefaultApiConventions))]
  

• operationId を生成して、ドキュメント、コード生成、他のサービスとの統合などの API 使用エクスペリエンスを大幅に向上させます。 HTTP 動詞フィルターに Name プロパティを含めることで、operationId を自動的に生成できます。

  [HttpGet("{Height}/{Width}", Name="GetPrice")]
  

続行