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ドキュメントを生成する方法を書いてみたいと思います。
