本エントリーは連載「ASP.NET Web APIそ使う」の第2回となります。連載の目次はこちら。
さて今回は、第1回で作成したWeb APIに対してSwaggerを適用します。
SwaggerとはRESTfulなAPIを管理する多岐にわたる成果物群のことで、API仕様記述の標準仕様やそのエディター、API仕様をWeb公開するためのユーザーインターフェースや、API仕様から各種言語のソースコードを自動生成するツールなどを含みます。MicrosoftやGoogleも立ち上げに関与しているそうです。
今回は前回作成したASP.NET Web APIアプリケーションへSwaggerのAPIドキュメント生成機能を適用し、次回のクライアントコード自動生成の事前準備を行います。
- 前提条件
- NuGetパッケージの適用
- 「XML ドキュメントファイル」を有効化
- 「Swashbuckle」に「XML ドキュメントファイル」を読み込ませる設定をする
- SwaggerのAPIドキュメントを確認する
前提条件
- Visual Studio 2017 Version 15.5.6
- .NET Framework 4.7.1
NuGetパッケージの適用
SwaggerをASP.NET Web APIプロジェクトへ簡単に適用するために、NuGet上に「Swashbuckle」というライブラリが公開されています。まずはこのライブラリをインストールします。
HelloWebApiプロジェクトを右クリックし「NuGetパッケージの管理...」を選択してください。
開かれたページでつぎの手順で「Swashbuckle」を検索し、インストールします。
- 「参照」を選択
- 検索ボックスに「Swashbuckle」を入力
- 検索結果から「Swashbuckle」を選択
- 「インストール」ボタンを押下
「XML ドキュメントファイル」を有効化
SwaggerのAPIドキュメントには、ソースコード上のXMLコメントが利用されます。詳細な仕様を有効にするため「XML ドキュメントファイル」を有効化します。なお有効化しなかった場合、詳細な説明は表示されませんがコード生成に必要な情報は利用可能です。
まずプロジェクトを右クリックして「プロパティ」を開き、つぎの手順で「XML ドキュメントファイル」を有効化します。
- 「ビルド」を選択
- 「XML ドキュメントファイル」のチェックボックスをチェック
チェックすると自動的にXML ドキュメントファイルのパスが設定されます。
「Swashbuckle」に「XML ドキュメントファイル」を読み込ませる設定をする
先にも記載した通り、「XML ドキュメントファイル」を生成しなくともSwaggerのドキュメントは生成されます。そのためデフォルトでは「XML ドキュメントファイル」を読み込む設定になっていないため、読み込み設定を有効化します。
ソリューション エクスプローラーで「App_Start」フォルダを開き「SwaggerConfig.cs」ファイルを開いてください。
ファイル内で「IncludeXmlComments」を検索すると、つぎのような箇所が見つかるはずです。
// If you annotate Controllers and API Types with // Xml comments (http://msdn.microsoft.com/en-us/library/b2s063f7(v=vs.110).aspx), you can incorporate // those comments into the generated docs and UI. You can enable this by providing the path to one or // more Xml comment files. // //c.IncludeXmlComments(GetXmlCommentsPath());
この最後の行のコメントを解除します。
// If you annotate Controllers and API Types with // Xml comments (http://msdn.microsoft.com/en-us/library/b2s063f7(v=vs.110).aspx), you can incorporate // those comments into the generated docs and UI. You can enable this by providing the path to one or // more Xml comment files. // c.IncludeXmlComments(GetXmlCommentsPath());
この状態では「GetXmlCommentsPath」メソッドが存在しないため、クラスの末尾につぎのように新しく作成します。
private static string GetXmlCommentsPath() { var baseDirectory = AppDomain.CurrentDomain.BaseDirectory; var commentsFileName = string.Format("{0}.XML", Assembly.GetExecutingAssembly().GetName().Name); var binFilePath = Path.Combine(baseDirectory, "bin"); var commentsFilePath = Path.Combine(binFilePath, commentsFileName); return commentsFilePath; }
以上でSwaggerの適用は完了です。
SwaggerのAPIドキュメントを確認する
F5キーを押下してデバッグを開始し、つぎのURLを閲覧してください。
http://localhost:9000/swagger
すると、つぎのような画面が表示されます。
APIの各仕様が閲覧できます。試しに「Employee」→「GET /api/Employees」を選択してみてください。つぎのように詳細な仕様が閲覧できます。
ここまでは「人間向け」のドキュメントでしたが、上のページの上部に表示されている、つぎのアドレスを表示するとプログラムから解析するためのJSON形式のAPIドキュメントを閲覧することができます。
http://localhost:9000/swagger/docs/v1
見やすいように変換すると、つぎのようなJSONになります。
{ "definitions": { "Employee": { "properties": { "BirthDay": { "format": "date-time", "type": "string" }, "Id": { "format": "int32", "type": "integer" }, "Name": { "type": "string" } }, "type": "object" } }, "host": "localhost:9000", "info": { "title": "HelloWebApi", "version": "v1" }, "paths": { "/api/Employees": { "get": { "consumes": [], "operationId": "GetEmployees", "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "responses": { "200": { "description": "OK", "schema": { "items": { "$ref": "#/definitions/Employee" }, "type": "array" } } }, "tags": [ "Employees" ] }, ...
ここでは詳細な解説は行いませんが、なんとなく意図は理解できるのではないでしょうか。
さてこれでSwaggerの適用は完了です。次回は、Swaggerの設定情報からクライアントコードを自動生成する方法を紹介します。