Swagger 2.0 に対応した ASP.NET Web API のドキュメントを作成する

この記事は、ASP.NET Advent Calendar 2015 の 8 日目 の記事です。
qiita.com
久しぶりに Swagger を使って ASP.NET Web API のドキュメントを作成してみたら、Swashbuckle の使い方が少し変わっていたので、変更点をまとめておきたいと思います。

Swagger とは

Swagger については、みそさんの記事が大変分かりやすくまとまっています。
miso-soup3.hateblo.jp
Swashbuckle の Version 5.x で Swagger 2.0 に対応したことで、仕様変更されました。
IIS 上で OWIN をホストさせる ASP.NET Web API を実装してみます。

前準備

Visual Studio で ASP.NET MVC のプロジェクトを作成し、Web API の OWIN 関連のライブラリを NuGet からインストールします。

• Install-Package Microsoft.AspNet.WebApi.Owin
• Install-Package Microsoft.Owin.Host.SystemWeb

Startup クラスを追加し、Web API のルーティングを設定します。

public class Startup
{
	public void Configuration(IAppBuilder app)
	{
		var config = new HttpConfiguration();
		config.Routes.MapHttpRoute(
			name: "DefaultApi",
			routeTemplate: "api/{controller}/{id}",
			defaults: new { id = RouteParameter.Optional }
		);
		app.UseWebApi(config);
	}
}

シンプルに Person のモデルとコントローラーを作成します。

public class Person
{
	public int Id { get; set; }
	public string Name { get; set; }
}

public class PersonController : ApiController
{
	public IEnumerable<Person> Get()
	{
		return new List<Person>() { new Person() };
	}

	public Person Get(int id)
	{
		return new Person();
	}

	public void Post([FromBody]Person user)
	{
	}

	public void Put(int id, [FromBody]Person user)
	{
	}

	public void Delete(int id)
	{
	}
}

Swashbuckle を使う

Swashbuckle.Core を NuGet からインストールします。

• Install-Package Swashbuckle.Core

Version 4.x では Swashbuckle.Core と Swashbuckle の２つのライブラリが必要でしたが、Version 5.x では Swashbuckle.Core のみで大丈夫です。

次に、プロジェクトのプロパティで、XML ドキュメントファイルのパスを設定しておきます。

最後に、Startup クラスで Swashbuckle の構成を設定します。

public class Startup
{
	public void Configuration(IAppBuilder app)
	{
		（省略）

		// Swashbuckle の構成
		config.EnableSwagger(c =>
		{
			c.SingleApiVersion("v1", "WebApplication2");
			c.IncludeXmlComments(GetXmlCommentsPath());
		})
		.EnableSwaggerUi(c =>
		{
		});

		app.UseWebApi(config);
	}

	private static string GetXmlCommentsPath()
	{
		return String.Format(@"{0}bin\WebApplication2.XML", System.AppDomain.CurrentDomain.BaseDirectory);
	}
}

Version 4.x では Bootstrapper や SwaggerSpecConfig で設定していましたが、Version 5.x では HttpConfiguration の拡張メソッドである EnableSwagger と EnableSwaggerUi を使います。XML コメントのパスを設定する以外に、SingleApiVersion で API のバージョンやタイトルも設定します。ここで指定したバージョンが JSON ドキュメントを取得する際の URL に含まれます。

動作確認

「/swagger/ui/index」にアクセスすると、Swagger UI のドキュメントページが表示されます。

Version 4.x では「/swagger/ui/index.html」でしたが、HTML の拡張子がなくなりました。
JSON ファイルを取得する場合は、「/swagger/docs/v1」からダウンロードできます。Version 4.x では「/swagger/api-docs」と「/swagger/api-docs//Person」に分かれていましたが、ひとつにまとまりました。

まとめ

先月、このような記事が発表され、Swagger がベースとなって標準化を進めていくようです。
www.publickey1.jp
Azure SDK 2.8.1 では、AutoRest を使って Swagger の JSON ファイルから REST Client のコードを自動生成できるようになりました。
少しずつ Swagger が普及しはじめているので、今後はドキュメントのカスタマイズなどを詳しくみていきたいと思います。