【連載】ASP.NET Web API を使おう：第2回 Swaggerを適用する

本エントリーは連載「ASP.NET Web APIそ使う」の第2回となります。連載の目次はこちら。

www.nuits.jp

さて今回は、第1回で作成したWeb APIに対してSwaggerを適用します。

SwaggerとはRESTfulなAPIを管理する多岐にわたる成果物群のことで、API仕様記述の標準仕様やそのエディター、API仕様をWeb公開するためのユーザーインターフェースや、API仕様から各種言語のソースコードを自動生成するツールなどを含みます。MicrosoftやGoogleも立ち上げに関与しているそうです。

swagger.io

今回は前回作成したASP.NET Web APIアプリケーションへ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」を検索し、インストールします。

1. 「参照」を選択
2. 検索ボックスに「Swashbuckle」を入力
3. 検索結果から「Swashbuckle」を選択
4. 「インストール」ボタンを押下

「XML ドキュメントファイル」を有効化

SwaggerのAPIドキュメントには、ソースコード上のXMLコメントが利用されます。詳細な仕様を有効にするため「XML ドキュメントファイル」を有効化します。なお有効化しなかった場合、詳細な説明は表示されませんがコード生成に必要な情報は利用可能です。

まずプロジェクトを右クリックして「プロパティ」を開き、つぎの手順で「XML ドキュメントファイル」を有効化します。

1. 「ビルド」を選択
2. 「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の設定情報からクライアントコードを自動生成する方法を紹介します。

www.nuits.jp