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 は下の状態になります。
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| using Swashbuckle.AspNetCore.Swagger; | |
| namespace MySampleWebApi | |
| { | |
| public class Startup | |
| { | |
| public Startup(IConfiguration configuration) | |
| { | |
| Configuration = configuration; | |
| } | |
| public IConfiguration Configuration { get; } | |
| public void ConfigureServices(IServiceCollection services) | |
| { | |
| services.AddMvc(); | |
| // Register the Swagger generator, defining one or more Swagger documents | |
| services.AddSwaggerGen(c => | |
| { | |
| c.SwaggerDoc("v1", new Info { Title = "My Sample API", Version = "v1" }); | |
| }); | |
| } | |
| public void Configure(IApplicationBuilder app, IHostingEnvironment env) | |
| { | |
| if (env.IsDevelopment()) | |
| { | |
| app.UseDeveloperExceptionPage(); | |
| } | |
| // Enable middleware to serve generated Swagger as a JSON endpoint. | |
| app.UseSwagger(); | |
| // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint. | |
| app.UseSwaggerUI(c => | |
| { | |
| c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Sample API V1"); | |
| }); | |
| app.UseMvc(); | |
| } | |
| } | |
| } |
この状態で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ドキュメントを生成する方法を書いてみたいと思います。