Swashbuckle を使用して OpenAPI ドキュメントを作成する

3 分

Visual Studio を使用して Web API を Azure API Management に発行するには、その前に OpenAPI 記述ドキュメントを用意する必要があります。

OpenAPI ドキュメントは、Web API のエンドポイントを検出するために API Management によって使用されます。 Swashbuckle ツールを使用すると、VanArsdel 開発者は Web API の OpenAPI 記述をこれまでよりも簡単に作成できるようになります。

OpenAPI とその機能について

OpenAPI ドキュメントでは、Web API に関する、プログラミング言語に依存しない標準のインターフェイス記述を定義します。これにより、人間とコンピューターの両方が、ソースコードへのアクセス、追加のドキュメント、ネットワークトラフィックの検査なしで、サービスの機能を検出して理解することができます。

OpenAPI イメージのスクリーンショット。

OpenAPI ドキュメントは、Web API のコントラクトです。これがありさえすれば、利用元のアプリケーションで Web API を理解して通信することができ、API が配置されている場所や実行されているかどうかを把握する必要はありません。

ASP.NET Core Web API アプリケーションから OpenAPI ドキュメントを生成する

ASP.NET Core Web API アプリから OpenAPI ドキュメントを生成するには、いくつかの方法があります。 Swashbuckle がこれを行うための最も一般的な方法です。

Swashbuckle プログラムのダウンロードのスクリーンショット。

簡単に使用でき、アプリにインストールすると、Swagger UI 画面が自動的に表示されます。

インベントリ管理が表示されている Swagger ユーザーインターフェイスのスクリーンショット。

Swashbuckle ではまた、すべての API エンドポイントの詳細、ペイロード構造、セキュリティ要件などを含む OpenAPI ドキュメントを即座に生成します。ここでは、VanArsdel の在庫管理用 Web API に関するサンプルドキュメントを示します。

OpenAPI ドキュメントコードのスクリーンショット。

次のユニットでは、演習でこの OpenAPI 機能を ASP.NET Core Web API アプリに対して有効にする方法を示します。