はじめに
Swashbuckle.AspNetCore を使うことで、ASP.NET Core MVC で実装した Web API に Swagger UI を組み込める。
Web API の動作確認をする程度ならこれで十分だけど、せっかく Swagger/OpenAPI を使うなら、クライアントのソースコードも生成したい。当然、自動化も。
Swashbuckle.AspNetCore.Cli と openapi-generator を使えばできそうなので試してみた。
Swashbuckle.AspNetCore.Cli
Swashbuckle.AspNetCore.Cli を使って swagger.json を生成する。
インストール
Swashbuckle.AspNetCore.Cli は .NET Core 2.1 SDK 以降で利用可能。.NET Core グローバルツールとしてインストールできる。
dotnet tool install -g swashbuckle.aspnetcore.cli
.NET Core 3.0 SDK 以降なら、.NET Core グローバルツールだけでなく、ローカルツールとしてもインストールできる。今回はこちらを使用。
dotnet new tool-manifest dotnet tool install swashbuckle.aspnetcore.cli
swagger.json 生成
dotnet swagger コマンドで swagger.json を生成する。
dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]
[output] には swagger.json、[startupassembly] は Swashbuckle.AspNetCore を組み込んだ Web API のアセンブリのパス、[swaggerdoc] には Startup 内で SwaggerDoc メソッドに渡している名前(ここでは "v1") を指定した。
openapi-generator
Swashbuckle.AspNetCore.Cli を使って出力した swagger.json からクライアントのソースコードを生成するには、openapi-generator を使う。
インストール
openapi-generator の CLI は npm でインストールするのが一番簡単。
npm install @openapitools/openapi-generator-cli -g
クライアントのソースコードを生成
TypeScript 版のクライアントのソースコードを生成してみた。
npx @openapitools/openapi-generator-cli generate -i swagger.json -g typescript-axios -o .\lib
-g にはソースコードの生成につかうジェネレーターを指定する。サポートしているジェネレーターは下記ページを参照。
自動化
Web API プロジェクトのビルド後イベントのコマンドラインに下記を追加。
dotnet swagger tofile --output $(OutDir)swagger.json $(TargetPath) v1 npx @openapitools/openapi-generator-cli generate -i $(OutDir)swagger.json -g typescript-axios -o $(OutDir)lib
これで Web API プロジェクトをビルドすると、自動で TypeScript のクライアントライブラリが生成されるようになった。
まとめ
Swashbuckle.AspNetCore を組み込んだ Web API のプロジェクトに対して、Swashbuckle.AspNetCore.Cli と openapi-generator-cli を使うことで、swagger.json 生成とクライアントソースコード生成がコマンドラインのみで行えるようになり、自動化できた。
