ASP.NET Web API では、Swashbuckle を使って Swagger ドキュメントを作成します。
具体的な手順は、過去の記事を参照してください。
gooner.hateblo.jp
例えば、GUID 型の ID を指定して取得する API を実装すると、Swagger ドキュメントでは string 型として扱われます。
[RoutePrefix("api/persons")] public class PersonController : ApiController { /// <summary> /// Person を取得します。 /// </summary> /// <param name="id"> /// <para>取得する Person ID。</para> /// <para>GUID 形式で指定します。</para> /// </param> /// <returns></returns> [Route] public Person Get(Guid id) { return new Person { Id = id, Name = "Test" }; } }
そのため、para タグを使ってパラメータのコメントを改行しているのですが、Swagger ドキュメントでは改行されずに読みづらくなってしまいます。
改行するには、Swagger ドキュメントをカスタマイズする方法があります。
元ネタは、GitHub の Issues に挙がっている内容です。
github.com
Swagger ドキュメントをカスタマイズする
Swashbuckle の IOperationFilter インターフェイスを利用すると、Swagger メタデータ プロセスのさまざまな部分をカスタマイズできる拡張ポイントが提供されます。
IOperationFilter インターフェイスを継承した FormatXmlCommentsFilter クラスを実装しました。
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<FormatXmlCommentsFilter>(); }) .EnableSwaggerUi(c => { }); app.UseWebApi(config); } }
Apply メソッドでパラメータのコメントに対して、para タグを p タグに変換するロジックを入れています。
public class FormatXmlCommentsFilter : IOperationFilter { public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) { foreach (var parameter in operation.parameters) { parameter.description = Formatted(parameter.description); } } private string Formatted(string description) { if (description == null) return null; return new StringBuilder(description).Replace("<para>", "<p>").Replace("</para>", "</p>").ToString(); } }
Swagger ドキュメントで、パラメータのコメントが改行されるようになります。
まとめ
IOperationFilter インターフェイスの Apply メソッドの引数を見ると、Swagger ドキュメントの JSON データを比較的自由にカスタマイズできることが分かります。
para タグぐらいは、Swashbuckle 側で対応してくれてもいい気もしますが、今回はカスタマイズして対応することにしました。
