ASP.NET Web API2 Owin で NSwag を利用する

概要

• ASP.NET Web API2 Owin で NSwag を導入する方法を纏めています。

コードサンプル

• GitHub にサンプルコードを置いています。

経緯

• これまで、Swagger UI の ライブラリとして Swashbuckle を利用していました。
• .NET Framework で利用する場合、Swashbuckle.WebApi を利用することになります。
• .NET Core版の Swashbuckle.AspNetCore とは異なり、Swashbuckle.WebApi は更新が途絶えております。
• Swashbuckle.WebApi は、Swagger UI の画面イメージも古いままでイマイチだったので、NSwag に乗り換えてみました。

参考情報

• 公式サイトにドキュメントとサンプルコードがありますので、参考にしつつ進めます。
  • Wikiページ
  • サンプルコード
• 時代の流れは ASP.NET Core ではありますが、ちゃんと .NET Framework版が存在するのは非常に有難いです。
• また、ASP.NET Core の情報になりますが、しばやんさんの情報も参考になりました。
  • ASP.NET Core Web API と NSwag を使って OpenAPI 定義を自動生成する

導入

• 導入のポイントとしては、下記の通りになります。
• 殆ど公式記載の情報通りなので、迷うことは無いかと思います。

NSwag.AspNet.Owin の追加

• NSwag.AspNet.Owin をNuGetより参照に加えます。
  

ミドルウェアの登録

• Startup.cs にてミドルウェアを登録します。
  • 今回は、SwaggerUI と Redoc の両方を登録してみました。

app.UseSwaggerUi3(typeof(Startup).Assembly, settings =>
{
    settings.Path = "/swagger";
});
app.UseSwaggerReDoc(typeof(Startup).Assembly, settings =>
{
    settings.Path = "/redoc";
});
app.UseWebApi(configuration);

web.configの変更

• web.config にて、上記URLの定義を追加します。

<system.webServer>
  <handlers>
    <remove name="ExtensionlessUrlHandler-Integrated-4.0" />
    <remove name="OPTIONSVerbHandler" />
    <remove name="TRACEVerbHandler" />
    <add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
    <add name="NSwagSwagger" path="swagger" verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
    <add name="NSwagRedoc" path="redoc" verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
  </handlers>
</system.webServer>

動作確認

• デバッグにてURLアクセスしてみると、どちらも正しく稼働しているかと思います。

• お馴染みの Swagger UI です。
  

• Redoc は可読性に優れているように感じます。
  

おまけ

• NSwag を利用することで OpenAPI の定義情報を CLI より出力することが出来ます。

• 出力には、NSwag.MSBuild を利用し、コマンドラインを実行します。

• 実行方法は、コマンドラインでオプションを渡す方法、及びオプション群を nswag.json を定義する方法があります。

  • 詳細は ドキュメント を参照ください。

• 以下、愚直にコマンド実行するサンプルになります。OpenAPI定義を取得することが出来ます。

.\packages\NSwag.MSBuild.13.11.1\tools\Win\nswag webapi2openapi /assembly:.\DotNetOwinWebApiSample.Api\bin\DotNetOwinWebApiSample.Api.dll /output:DotNetOwinWebApiSample.Api.json