今回は ASP.NET Core 6 で Swashbuckle.AspNetCore の CLI を使って json または YAML で定義ファイルを出力するポイントを書いていきます。
ASP.NET Core 6 と書きましたが 3系や5系も基本的には一緒です。2系だと多少異なりますがもう使ってないと思うので触れません。
前提として、なぜ定義ファイルの出力を CLI でしたいのかは CI/CD の時に使いたいからです。定義ファイルを GitHub Actions での CI/CD で使う話を後日のブログでいています。
GitHub Actions で Azure API Management の CI/CD (ASP.NET Core 6) - BEACHSIDE BLOG
ビルド時に毎回定義ファイルを生成する方法もありますが、今回はそれには触れません。
あと、前提として今回はローカル環境での実行なので Windows でやってます。
- 事前知識: Swagger (Swashbuckle) の導入と基本的な使い方
- 準備: プロジェクトの作成
- 本題: Swashbuckle.AspNetCore.Cli を使ったスキーマファイルの出力
- まとめ
事前知識: Swagger (Swashbuckle) の導入と基本的な使い方
以前に書いた時とさほど変わっていないのでそのリンクはっておきます。
公式ドキュメントも充実しているのでリンクも貼っておきます。
準備: プロジェクトの作成
Swashbuckle.AspNetCore.Cli を使ったスキーマファイルの出力に進む前に、せっかくなので ASP.NET Core Web API を作るところからやっていきます。
まずは VS 2022 で 新しいプロジェクトの作成 をクリックしていきます。
テンプレートの選択です。今回は ASP.NET Core Web API を選びます。
入力項目は適宜設定して、次へ をクリックして進みます。
「追加情報」が表示されます。ここで注意するのは以下2点くらいでしょうか。
- フレームワーク: 今回は .NET 6.0 を選びます。
- OpenAPI サポートを有効にする: チェックをオンにします。オフだと自分で構成しなきゃならんです (大した手間でもないですが)
これで 作成 をクリックしたらプロジェクトの出来上がりです。
これでデバッグしたときには Swagger UI が起動して利用できる状態になっています。
これをいい感じにカスタマイズするには先述の「事前知識」のリンクを見ましょう♪
本題: Swashbuckle.AspNetCore.Cli を使ったスキーマファイルの出力
基本的には こちらのドキュメント の通りですが、細かいところで躓くポイントがあるので、出力方法と注意点を書いていきます。
NuGet パッケージのインストール
Web API のプロジェクトで、NuGet パッケージ Swashbuckle.AspNetCore.Swagger のインストールが必要なので最新版をインストールします。ついでに最初からインストール済みの Swashbuckle.AspNetCore のバージョンも最新にしておきます。
tool-manifest のセットアップ
まず、Local tool のインストールが必要です。
ということでまずは、ソリューションのルートでターミナルを開きます。私は PowerShell がデフォで起動しますがコマンドプロンプトでも変わらんはずです。
そして以下のコマンドを実行します。
dotnet new tool-manifest
これで、ソリューションのルートをみると .config/dotnet-tools.json ができました。これの manifest のファイルは今回はいじる必要はありません。
このファイルは、ソリューションのルートにあればその下のディレクトリのプロジェクトをディレクトリでコマンドを実行しても動作します。特別な理由がない限りはソリューションのルートに作れば OK です。
Swashbuckle.AspNetCore.Cli のインストール
このコマンドを実行して Swashbuckle.AspNetCore.Cli をインストールします。
dotnet tool install --version 6.4.0 Swashbuckle.AspNetCore.Cli
プロジェクトのビルド
定義ファイルの出力には、ビルドの成果物 ("build artifacts" を日本語にするの違和感ある..) が必要なので、まずはビルドします。今回はソリューションのルートで csproj の指定なしでやっちゃいます。Configuration は Release でやります。
dotnet build -c Release
定義ファイルの出力
定義ファイルの出力の基本的なコマンド定義は dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc] です。
JSON の定義ファイルを出力
ソリューションのルートでこのままコマンドを実行する場合は、こんな感じでコマンドを実行します。
dotnet swagger tofile --output swagger.json WebApplication1/bin/Release/net6.0/WebApplication1.dll v1
これで、ソリューションのルートに swagger.json という名前で定義ファイルが出力できました。
YAML の定義ファイルを出力
YAML で出力したい場合は --yaml をつけるだけです。
dotnet swagger tofile --yaml --output swagger.yml WebApplication1/bin/Release/net6.0/WebApplication1.dll v1
ソリューションのルートに swagger.yml という名前で定義ファイルが出力できます。
せっかくなので出力された YAML が正しくできてるか試してみます。Swagger Editor を開いて、生成された YAML を貼り付けてみると正しく生成されていることが確認できます。JSON でも同様です。
定義ファイルの出力コマンド実行時の注意点
dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc] をやれって話ですがその注意点。
相対パスの指定方法
先頭に / を付けると相対パスではなく絶対パスとして扱われるので注意です。
[swaggerdoc] (バージョン) の指定
今回のサンプルでは v1 を指定していますが、これは出力された定義ファイルのバージョンになります。つまり定義されていない勝手なバージョンを指定することはできません。適当なバージョンをつけるとこんなエラーになります。
ではその指定はどこでやるかは、コード側でやります。Web API の Program.cs を開いてみましょう。デフォルトでは v1 になっていますが見えないのでわかりにくいです。例えば v2 にするにはこんな感じで変更します。
- 10-13行目: バージョンの指定を指定します。
- 21-25行目: デバッグ環境とかで Swagger UI を起動するためにエンドポイントの指定をします。
複数のバージョンを定義することもできますが今回は触れないでおきます。
これで v2 のドキュメントができます。
この状態でビルドしてから dotnet swagger tofile で v2 を指定すると正常に出力されます。v1 はなくなったのでもちろんエラーになります。
日本語使うのやめとこ
今回に限った話ではないしもしかしたらどうでもよさそうですが、日本語とかダブルバイトの文字の利用はあまりお勧めできません。英語圏の OSS 開発者が普段使わないダブルバイトの文字を気にしてないことは少なくないし、そのせいでバグを踏むのは実際に何度も見てきてるので、使わないに越したことはありません。
まとめ
以下のドキュメントで私的に読み取りにくい点を書いてみましたが、今日はここまでにします。
