プルリクエストをオープンし、ドキュメントは問題なくビルドされました。しかし3日後、同僚から連絡がありました。ステージングサーバーがすべてのリクエストを拒否しているのです。原因は、名前を変更したパスを指す「宙ぶらりんの$ref」がOpenAPIファイルにあることでした。エディタでは仕様は正しく見え、Swagger UIでもレンダリングされました。しかし実際には有効ではなく、出荷前にパイプラインの何もそれを検知しませんでした。
それこそがSwaggerコマンドラインツールのための仕事です。人間が気付く前に壊れた仕様をキャッチすることです。「swagger cli」という言葉は通常、@apidevtools/swagger-cliを指します。これは、OpenAPIドキュメントをチェックし、複数のファイルに分かれた仕様を1つにまとめるvalidateとbundleの2つのコマンドを持つ小さなnpmパッケージです。これは非常に便利なツールであり、このガイドではその適切な使用方法を説明します。また、このツールがカバーできない範囲も示します。なぜなら、仕様の検証はAPIを信頼するための最初の半分に過ぎないからです。後半は、実際のリクエストを送信し、返ってくる内容を検証することであり、そこはApidog CLIのようなランナーが引き継ぎます。
つまり、これは実質的に2つのターミナル作業に相当します。まず、swagger-cli（またはその後継）で仕様をlintおよびバンドルして、契約が健全であることを確認します。次に、コマンドラインから実行中のAPIに対して実際のテストを実行し、実装が契約と一致していることを確認します。この記事ではその両方を取り上げ、どのツールがどの役割を担うかを正直に説明し、それぞれのコピー＆ペースト可能なコマンドを提供します。
「swagger cli」が実際に指すもの
「swagger」という単一の公式バイナリは存在しません。この名前はいくつかの異なるツールを指し、どれを意味するかを知ることで多くの混乱を避けることができます。
@apidevtools/swagger-cliは、ほとんどの人が意味するパッケージです。そのバイナリはswagger-cliで、2つのことを行います。OpenAPIまたはSwagger 2.0ドキュメントを検証すること、そして複数のファイルに分かれた仕様を1つのファイルにバンドルすることです。この記事の前半では、これに焦点を当てます。swagger-codegenは、SmartBearによる別のより大規模なプロジェクトで、仕様からクライアントSDKとサーバスタブを生成します。全く異なる役割で、記事の最後に少し触れます。- Swagger UIとSwagger Editorは、CLIではありません。これらはブラウザで仕様をレンダリングおよび編集します。まだフォーマットを学んでいる段階であれば、SwaggerとOpenAPIの入門が適切な出発点です。
このガイドは、検証、バンドル、lint、そしてテストといったコマンドライン作業についてです。代わりに、設計およびテストプラットフォームのより広範な概要を知りたい場合は、Swaggerの代替ツールのまとめがGUI側をカバーしています。
swagger-cliのインストール
このツールはnpmパッケージとして提供されています。グローバルにインストールします。
npm install -g @apidevtools/swagger-cli
解決されたことを確認します。
swagger-cli --version
swagger-cli --help
Node.jsが唯一のシステム依存関係です。NodeがすでにインストールされているどんなマシンやCIイメージでも実行できます。グローバルにインストールしたくない場合は、npx @apidevtools/swagger-cli ...でオンデマンドで呼び出すことができ、これは一時的なビルドランナーで便利です。
依存する前に知っておくべきことの1つは、メンテナがswagger-cliを非推奨としてマークしていることです。READMEには、貢献者が少ない大規模なユーザーベースのメンテナンス負担を理由に、その旨が明記されています。これはまだ機能しており、今日でも多くのパイプラインで実行されていますが、新しいプロジェクトでは、積極的にメンテナンスされている後継であるRedocly CLIが推奨されています。その移行については以下のセクションで説明しますので、納得した上で判断できます。
swagger-cliを使った仕様の検証
主要なコマンドはvalidateです。仕様ファイルを指定して実行します。
swagger-cli validate openapi.yaml
ドキュメントが健全であれば、1行の確認メッセージと終了コード0が表示されます。問題がある場合は、問題の内容を説明するエラーメッセージと非ゼロの終了コードが表示されます。これはパイプラインでまさに必要な動作です。
validateは内部で2つのチェックを実行し、どちらか一方を無効にできます。
swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml
--no-schemaは、ドキュメントの正しい構造を確認するOpenAPI JSONスキーマに対する検証をスキップします。--no-specは、重複した操作IDやどこにも指していない$refのようなものを捕捉する、仕様規則そのものに対する意味的チェックをスキップします。ほとんどの場合、両方を有効にしたいので、それがデフォルトです。これらのフラグは、いずれかのレイヤーが意図的に許可したいと考える何かを指摘している稀なケースのために存在します。
validateがうまく捕捉するもの：不正な形式のYAML、必須フィールドの欠落、壊れた$refポインタ、および仕様が解析不能になる構造上の誤り。validateが捕捉しないもの：チームのスタイルを強制すること。説明のない仕様、一貫性のない命名、例のない仕様でも、OpenAPIの規則に違反しないため、問題なくvalidateを通過します。そのような独断的なチェックにはリンターが必要であり、それが次のセクションです。
検証だけが目的であれば、OpenAPI仕様を検証する方法に関する詳細な解説では、知っておくべきいくつかのツールとエッジケースを比較しています。
複数ファイル仕様のバンドル
実際の仕様が1つのファイルに収まることはめったにありません。スキーマをcomponents/ディレクトリに分割し、$refで参照し、ルートファイルを読みやすく保ちます。これは良い習慣ですが、多くの下流ツールは単一の自己完結型ドキュメントを求めます。bundleコマンドはツリーを平坦化します。
swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml
知っておくべきフラグは次のとおりです。
-o, --outfile <file>は、結果を標準出力に出力する代わりにファイルに書き込みます。-t, --type <json|yaml>は出力フォーマットを設定します。デフォルトはjsonなので、YAMLで出力したい場合は-t yamlを渡します。-r, --dereferenceは、外部ファイルを1つのドキュメントにまとめるだけでなく、すべての$refを完全にインライン化します。これにより、ファイルサイズは大きくなりますが、参照が残らないため、一部のコンシューマが必要とする場合があります。-f, --format <spaces>はインデントを制御し、デフォルトは2スペースです。-w, --wrap <column>は、長いYAML文字列の折り返し行長を設定します。
通常のバンドルと--dereferenceの違いは重要です。通常のバンドルは内部の$refポインタを保持しつつ、すべての分離されたファイルを1つにまとめるため、ドキュメントはポータブルになります。--dereferenceはすべての参照をインラインオブジェクトに解決するため、ファイルサイズは膨大になりますが、コンシューマがポインタを解決する必要がないことを保証します。配布用には通常のバンドルを使用し、特定のツールが要求する場合にのみデリファレンス形式を使用します。
一般的なパターンは、ビルドの一部として検証とバンドルを1ステップで行うことです。
swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json
&&は、検証が成功した場合にのみバンドルが実行されることを意味するため、壊れた仕様からビルド成果物が生成されることはありません。
CIへのswagger-cliの組み込み
検証は、誰かが思い出したときではなく、変更があるたびに実行されるときに最も価値があります。高速なゲートとしてパイプラインに組み込みましょう。以下は、無効な仕様でビルドを失敗させるGitHub Actionsのステップです。
name: Validate OpenAPI spec
on:
pull_request:
paths:
- 'openapi.yaml'
- 'components/**'
jobs:
validate-spec:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Validate spec
run: npx @apidevtools/swagger-cli validate openapi.yaml
swagger-cli validateは不正な仕様で非ゼロで終了するため、このステップは赤くなり、プルリクエストには失敗したチェックが表示されます。追加の構成は不要です。pathsフィルタは、仕様が変更されていない場合にジョブが実行されるのを防ぎ、CIの時間を節約します。
これは、APIリポジトリに追加できる最も安価な品質ゲートです。数秒しかかからず、「ドキュメントが嘘をついていた」という種類のバグが下流に到達するのを完全に防ぎます。
検証だけでなくLintが必要な場合
検証は、「これは合法的なOpenAPIドキュメントか？」という1つの質問に答えます。Lintingは、より難しい質問に答えます。「これは私たちのチームの基準で良いOpenAPIドキュメントか？」これらは同じではなく、swagger-cliは最初の質問にしか答えません。
たとえば、スタイルガイドがすべての操作にsummary、すべてのプロパティにdescription、すべてのパスにケバブケースの使用を要求しているとします。仕様はこれら3つすべてに違反してもswagger-cli validateをパスすることができます。なぜなら、これらのルールはOpenAPI仕様の一部ではないからです。リンターを使用すると、それらのルールをエンコードして強制することができます。
これが、チームがRedocly CLIに移行する主な理由です。これはswagger-cli自体が推奨する、メンテナンスされている後継ツールです。Redocly CLIは同じ検証とバンドルをカバーし、さらに実際のLintingエンジンを追加します。
Redocly CLIへの移行
コマンド名が似ているため、移行は小規模です。後継ツールをインストールします。
npm install -g @redocly/cli
検証の同等コマンドはlintです。古い動作に厳密に合わせるには、最小限のルールセットを拡張します。
redocly lint --extends=minimal openapi.yaml
代わりにデフォルトのルールセットで実行すると、より強力な推奨ルールセットが適用され、そこにLintingの価値が現れます。redocly.yamlファイルでルールを設定し、それぞれをerrorまたはwarnに設定したり、組織固有のチェックのためにカスタムプラグインを作成することもできます。
バンドルはほぼ1対1で対応しています。
redocly bundle openapi.yaml -o dist/openapi.yaml
フラグ名はわずかに変更されます。swagger-cliの-o/--outfileは--outputになり、-t/--typeは--extになり、-r/--dereferenceは-d/--dereferencedになります。もし古いスクリプトでショートフラグを使用していた場合は、簡単な検索と置換で対応できます。仕様チェックツールのより広範な比較については、最高のOpenAPIバリデータツールの分析でRedoclyを代替ツールと比較しています。
要するに、新しく始める場合はRedocly CLIを使用しましょう。既存のswagger-cliステップが機能している場合は、緊急性はありませんが、今後のパスは明確であり、名前変更は機械的な作業です。
仕様ツールではカバーできない半分
これまでに議論してきたすべてのツールの限界はここにあります。swagger-cli validateは、仕様が適切に形成されていることを確認します。redocly lintは、チームのスタイルに従っていることを確認します。どちらも、実行中のAPIに単一のリクエストを送信することはありません。仕様は書面上では完璧でも、実装が500を返したり、約束したフィールドを省略したり、クエリパラメータを完全に無視したりする可能性があります。
そのギャップを埋めるには機能テストが必要です。つまり、実際のエンドポイントに実際のリクエストを送信し、ステータスコード、レスポンスボディ、およびその中の値をアサートすることです。これは異なるカテゴリのツールであり、Apidogがワークフローに適合する場所です。
ApidogはオールインワンのAPIプラットフォームです。OpenAPI仕様をインポートすると、その定義から対話型ドキュメント、モックサーバー、そしてアサーションと連携できるテストシナリオが、すべてワークスペースから離れることなく利用できます。インポートは直接行われます。SwaggerまたはOpenAPIのインポートと実行可能なリクエストの生成に関するガイドではその手順が説明されており、手動で構築する代わりに仕様から完全なテストコレクションを生成できます。
ターミナルにとって重要なのは、npmパッケージapidog-cliとして公開されているコマンドラインランナーです。これをインストールし、保存されたシナリオをヘッドレスで実行します。
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
-tフラグはテストシナリオID、-eは環境ID、-rはcli、html、json、junitなどのレポート形式を選択します。swagger-cliと同様に、クリーンなステータスコードで終了するため、アサーションが失敗するとパイプラインが赤くなります。swagger-cliとは異なり、チェックしているのはAPIのライブ動作であり、それを記述するファイルの形式だけではありません。完全なフラグリファレンスとCIの例については、Apidog CLI完全ガイドを参照するか、apidog run --helpを実行して現在のオプションを確認してください。最初のシナリオを設定したい場合は、Apidogをダウンロードし、仕様をインポートすると、シナリオのCI/CDタブからランナーコマンドをコピーできます。
完全なターミナルワークフロー
この2つの部分を組み合わせると、契約と実装を順番にチェックするパイプラインが完成します。
# 1. 仕様は適切に形成され、スタイルに合っているか？
redocly lint --extends=minimal openapi.yaml
# 2. 単一の配布可能なドキュメントを生成する。
redocly bundle openapi.yaml -o dist/openapi.yaml
# 3. 実行中のAPIは実際に契約と一致しているか？
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit
ステップ1では、不正な形式またはスタイルに合わない仕様で速やかに失敗します。ステップ2では、ドキュメントやSDKジェネレーターが消費する成果物を生成します。ステップ3では、実際のリクエストを送信してレスポンスをアサートするため、ビルドがグリーンであれば、契約とそれを支えるコードの両方が健全であることを意味します。各ステップは失敗時に非ゼロで終了するため、チェーン全体が、NodeがインストールされているCIランナーに組み込める単一のゲートとなります。
今日のテストが静かになってしまった仕様適合ツールに依存している場合、DreddなしでAPIを仕様に対して検証するという記事は、同じ契約と実装のアイデアを別の角度からカバーしています。
swagger-codegenに関する注意
「swagger cli」を検索している人々は、実際にはswagger-codegenを求めている場合があります。これは異なる目的を持つ異なるツールです。これはOpenAPI仕様を読み込み、数十の言語でクライアントSDK、サーバーのスタブ、およびドキュメントを生成します。公開された仕様から型付きクライアントをブートストラップするのに非常に役立ち、Swaggerファミリーの中で最も有能なコード生成オプションと呼んでも差し支えありません。
この記事でカバーされている意味での検証、lint、テストは行いません。生成は、健全な仕様がすでにあることを前提としています。入力が壊れている場合、出力も同様に壊れています。したがって、コード生成ワークフローであっても、その前に検証またはlintステップを置くことが望ましいです。これらのツールは互いに補完し合う関係であり、代替するものではありません。