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

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

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

## コードサンプル
- [GitHub](https://github.com/tYoshiyuki/dotnet-owin-webapi-sample) にサンプルコードを置いています。

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

## 参考情報
- 公式サイトにドキュメントとサンプルコードがありますので、参考にしつつ進めます。
    - [Wikiページ](https://github.com/RicoSuter/NSwag/wiki/OWIN-Middleware)
    - [サンプルコード](https://github.com/RicoSuter/NSwag/tree/master/samples/WithMiddleware/Sample.NetOwinMiddleware)
- 時代の流れは ASP.NET Core ではありますが、ちゃんと .NET Framework版が存在するのは非常に有難いです。
- また、ASP.NET Core の情報になりますが、しばやんさんの情報も参考になりました。
    - [ASP.NET Core Web API と NSwag を使って OpenAPI 定義を自動生成する](https://blog.shibayan.jp/entry/20200519/1589877269)

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

### NSwag.AspNet.Owin の追加
- NSwag.AspNet.Owin をNuGetより参照に加えます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/353069/e8ff092a-fefb-ae07-0593-c4cbb22529cc.png)

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

```cs

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の定義を追加します。

```xml

<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 です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/353069/23ecb244-6334-1c07-b3d9-347020324e66.png)

- Redoc は可読性に優れているように感じます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/353069/1ee237f6-a545-61a5-e88d-772deb50e2f0.png)

## おまけ
- NSwag を利用することで OpenAPI の定義情報を CLI より出力することが出来ます。
- 出力には、NSwag.MSBuild を利用し、コマンドラインを実行します。
- 実行方法は、コマンドラインでオプションを渡す方法、及びオプション群を nswag.json を定義する方法があります。
    - 詳細は [ドキュメント](https://github.com/RicoSuter/NSwag/wiki/CommandLine) を参照ください。

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/353069/6d621ded-6ea7-212a-5caa-2c2fc57e8325.png)