2017年9月8日

ASP.NET WebAPIにSwaggerを組み込む



1. ASP.NET Core Web APIを新規作成する


Visual Studio 2017でASP.NET CoreのWeb APIプロジェクトを新規作成します。


デフォルトでControllersフォルダの中にValuesControllerがあるので、この名前をProductsControllerに変更し、さらにUsersControllerを追加します。

新規にResourcesフォルダを作成してその中にProductクラスとUserクラスを作成しておきます。

その後ProductsControllerとUsersControllerを編集してダミーのデータをJSONで返す様にした状態のソースコードが下記になります。(コミットにbefore-swaggerタグが付いています。)

https://github.com/mikehibm/AspNetCoreWebApiSwagger/tree/before-swagger

Ctrl+F5キーで実行すると商品とユーザーの情報がJSONで返って来るのが分かります。


この状態でWeb APIとしては動いているので、次にSwaggerを組み込んでAPIのドキュメント(メタ情報)に外部からアクセス出来るようにしてみます。



2. Swaggerを組み込む


Visual Studio内でPackage Managerコンソールを開いて、次のコマンドを打ち込みます。

Install-Package Swashbuckle.AspNetCore

その後、下のサイトを参考にStartup.csファイルを編集します。と言っても数行を追加するだけなので簡単です。

ASP.NET Web API Help Pages using Swagger


編集後の Startup.cs は下の状態になります。




この状態でCtrl+F5キーを押して実行し、http://localhost:xxxxxxx/swagger/ のURLを開くと、Swagger UIの画面が開いてAPIのドキュメントを閲覧する事が出来るようになっています。



ただこの段階ではせっかくソースコードに書き込んだコメントが反映されていないので、次にそれらが反映されるようにします。



3. XMLコメントをSwaggerに反映させる


まず、プロジェクトの設定で「XMLドキュメントファイル」の自動生成を有効化しておく必要があります。



この状態で一旦プロジェクトをビルドすると、指定したファイル名でXMLファイルが出来るはずです。このファイルをVisual Studioのソリューションエクスプローラ上で右クリックして、「プロジェクトに含める」を選択しておきます。

さらに、XMLファイルを選択した状態でF4キーを押してプロパティウインドウを表示し、下のようにプロパティを変更しておきます。これは後でこのプロジェクトをPublishする際に必要になります。





次に、Startup.csファイルの中で services.AddSwaggerGen() メソッドを呼んでいる箇所があるので、そのブロック内に下の3行を追加します。

var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "MySampleWebApi.xml");
c.IncludeXmlComments(xmlPath);

これで再度実行するとソースコード内でクラス単位やメソッド単位で「///」を使って書いたコメントがSwagger UIの画面にも反映されます。




4. まとめ


ASP.NET CoreのWeb APIプロジェクトにSwaggerを組み込んでAPIのドキュメントを表示させるようにする事は、上の通りかなり手軽に出来ます。

ASP.NET Coreでなく従来のASP.NET MVCのプロジェクトでもほぼ同じ手順でSwaggerの組み込みが可能です。

次回はSwaggerが生成した情報を使ってPDFドキュメントを生成する方法を書いてみたいと思います。