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

削除するには、２通りの対応があります。
元ネタは、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);
				}
			}
		}
	}
}