ROMANCE DAWN for the new world

Microsoft Azure を中心とした技術情報を書いています。

ASP.NET Web API の Swagger ドキュメントからパラメータのモデル名を削除する

ASP.NET Web API では、Swashbuckle を使って Swagger ドキュメントを作成します。
具体的な手順は、過去の記事を参照してください。
gooner.hateblo.jp

アクションメソッドに FromUri 属性を指定すると、URI のパラメータを自分で定義したクラスにバインドできます。開始と終了のコードを指定して検索できる API であれば、次のように実装できます。

[RoutePrefix("api/persons")]
public class PersonController : ApiController
{
	[Route]
	public IEnumerable<Person> Get([FromUri]PersonGetParameters model)
	{
	}
}

public class PersonGetParameters
{
	public string StartCode { get; set; }
	public string EndCode { get; set; }
}

Swagger UI で確認すると、以下のように表示されます。

f:id:TonyTonyKun:20160725153354p:plain
API の動作としては、以下のどちらの URL でもリクエストできるので間違いではないのですが、少し格好悪いので Swagger ドキュメントから「model.」を削除したくなります。

  • api/persons?model.startCode=001&model.endCode=002
  • api/persons?startCode=001&endCode=002

削除するには、2通りの対応があります。
元ネタは、GitHub の Issues に挙がっている内容です。
github.com

モデル名を含めたリクエストを許可しない

API の URL ルーティングとして、モデル名を含めたリクエストを許可しないことで、Swagger ドキュメントからも「model.」が削除されます。必要な実装は、FromUri 属性の Name プロパティに Empty をセットするだけです。

[Route]
public IEnumerable<Person> Get([FromUri(Name = "")]PersonGetParameters model)
{
}

f:id:TonyTonyKun:20160725153412p:plain

Swagger ドキュメントをカスタマイズする

Swashbuckle の IOperationFilter インターフェイスを利用すると、Swagger メタデータ プロセスのさまざまな部分をカスタマイズできる拡張ポイントが提供されます。
IOperationFilter インターフェイスを継承した MyOperationFilter クラスを実装しました。

public class Startup
{
	public void Configuration(IAppBuilder app)
	{
		var config = new HttpConfiguration();
		config.MapHttpAttributeRoutes();

		// Swashbuckle の構成
		config.EnableSwagger(c =>
		{
			c.SingleApiVersion("v1", "WebApplication4");
			c.IncludeXmlComments($@"{AppDomain.CurrentDomain.BaseDirectory}bin\WebApplication4.XML");
			c.OperationFilter<MyOperationFilter>();
		})
		.EnableSwaggerUi(c =>
		{
		});

		app.UseWebApi(config);
	}

}

Apply メソッドでパラメータ名を変換すると、Swagger ドキュメントからも「model.」が削除されます。

public class MyOperationFilter : IOperationFilter
{
	public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
	{
		if (operation.parameters != null)
		{
			foreach (var pram in operation.parameters)
			{
				// 例)"model.startCode" → "startCode" に変換
				var index = pram.name.IndexOf(".");
				if (index != -1)
				{
					pram.name = pram.name.Substring(index + 1);
				}
			}
		}
	}
}

まとめ

シンプルな API であれば、アクションメソッドに int や string などのプリミティブ型で十分対応できますが、指定できる検索条件が多くなると自分で定義したクラスにパラメータをバインドしたくなります。
その際に、モデル名を削除する方法を2通り紹介しました。

  • モデル名を含めたリクエストを許可しない
  • Swagger ドキュメントをカスタマイズする

Swagger ドキュメントをカスタマイズする方法では、重複したパラメータ名が出力される可能性があります。
1つの API で複数の URL ルーティングをサポートする必要性はないので、モデル名を含めたリクエストを許可しない方が良いのかなと思います。