壊れたSwaggerファイルは、めったにそれ自体を知らせることはありません。YAMLは問題なく解析され、ドキュメントページもレンダリングされます。しかし、フロントエンド開発者があなたの仕様からクライアントを生成しようとすると、requiredフィールドの欠落でビルドが失敗し、あなたの「完成した」API記述に3コミット前の$refにタイプミスがあったことが判明します。仕様は最初から間違っていたのです。誰かの午後の時間を無駄にするまで、誰も教えてくれませんでした。
それがSwaggerバリデーターの役割です。OpenAPIまたはSwaggerファイルを読み込み、誰かがそれを消費する前に、ドキュメントが実際に有効であるかどうかを教えてくれます。「見た目が正しいか」ではなく、「OpenAPI仕様に準拠しているか、すべての参照を解決しているか、ツールが信頼できるスキーマを記述しているか」を確認します。バリデーターは、目に見えない構造的なバグを、数時間のダウンストリームデバッグの代わりに数秒で修正できる、行番号付きの明確なエラーに変えてくれます。
Swaggerバリデーターが実際にチェックすること
まず、命名について。「Swagger」と「OpenAPI」は、歴史上の異なる時点で同じものを指します。この形式はバージョン2.0まではSwaggerと呼ばれ、その後OpenAPI Initiativeに寄贈され改名されました。3.0、3.1、3.2はすべてOpenAPIです。しかし、人々は習慣的に今でも「Swaggerバリデーター」と言い、ほとんどのツールはSwagger 2.0とOpenAPI 3.xの両方を受け入れます。バージョン履歴が曖昧な場合は、Swagger vs OpenAPIの解説がそれを明確にします。最近のバージョンの違いについては、OpenAPI 3.2 vs 3.1 vs 3.0で何が変わったかをご覧ください。
実際のバリデーターは、以下の3つの役割を順に果たします。
- 解析。 ファイルが有効なYAMLまたはJSONであるか？ 余計なタブ、重複したキー、閉じられていない括弧があると、ドキュメントはロードされません。これは最も安価に捕捉できるエラーであり、リリースして最も恥ずかしいものです。
- 構造の検証。 ドキュメントはOpenAPIスキーマに準拠しているか？ すべての操作には
responsesオブジェクトが必要です。すべてのパラメーターにはin値が必要です。$refは存在する何かを指している必要があります。これがほとんどの実際のバグが潜んでいる場所です。 - 参照の解決。 OpenAPIドキュメントは、再利用可能なスキーマを結合する
$refポインタでいっぱいです。バリデーターはすべてのポインタをたどり、ターゲットが欠落している場合、仕様が禁止する形で循環している場合、または間違ったファイルを指している場合に失敗します。
これら3つすべてをクリアすれば、準拠したツール、コードジェネレーター、モックサーバー、ドキュメントレンダラーのいずれもが詰まることなく読み取れるドキュメントになります。いずれか1つでも失敗すると、ターミナルよりも不便な場所でその失敗が表面化します。
後で問題となるエラーを捕捉する
検証は、それがないと何がすり抜けてしまうかを見るまでは抽象的に感じられます。これらは、エディターでは無害に見えるが、ダウンストリームで実際の問題に発展する仕様のミスです。
壊れた$refポインタ。 スキーマ名をUserからUserProfileに変更したが、レスポンスボディの奥深くにある参照の1つを見落とした場合。YAMLはまだ解析されます。ドキュメントはページの残りの部分をまだレンダリングします。しかし、コードジェネレーターはぶら下がったポインタに遭遇し、型のないクライアントを出力するか、単にクラッシュします。バリデーターは、保存した瞬間に壊れた$refをフラグ付けします。
スキーマと例の不一致。 スキーマではageが整数であると示されているのに、例では"age": "thirty"と示されている場合。Swagger UIはどちらも問題なく表示します。しかし、その仕様から構築されたモックサーバーは、コンシューマーが数値を期待する場所で文字列を返し、3つのチームを隔てた契約テストが、誰にもあなたのファイルにまで遡れない理由で赤になります。
欠落している必須要素。 responsesのない操作。URLテンプレートで宣言されているがparametersで定義されていないパスパラメーター。requestBodyにcontentがない場合。これらはそれぞれ技術的に不正な形式のドキュメントであり、どのツールが最初に仕様を読み取るかによって異なるダウンストリーム症状を引き起こします。
型とフォーマットのずれ。 バックエンドがUnixタイムスタンプとして返すフィールドにformat: date-timeが指定されている場合。実際には配列であるものにtype: stringが指定されている場合。これらは構造的検証は通過しますが、仕様と実行中のAPI間の契約を破棄します。これは後で説明する別の問題です。
このパターンは一貫しています。仕様のエラーは、あなたがそれを作成した時点では目に見えず、他の誰かがそれを消費する時点では高くつきます。検証は、そのコストを安価な時点に戻すのです。
手動でSwaggerファイルを検証する方法
始めるためにプラットフォームは必要ありません。現在、仕様を検証する3つの簡単な方法があります。
Swagger Editor。 YAMLをSwagger Editorに貼り付けると、入力と同時に検証が行われ、右余白に行番号付きでエラーが下線表示されます。これは単一ファイルを素早くサニティチェックする最も速い方法であり、無料です。限界は、これが単一のテキストボックスであることです。ドキュメントは検証しますが、実際のAPIがそれにまだ一致しているかどうかについては何もせず、ビジュアルスキーマビルダーなしでYAMLを手書きすることになります。形式を学ぶにはそれで十分ですが、チームが依存する仕様の場合、これは複数のタブを必要とするワークフローの中の一つのタブに過ぎません。
Spectralのようなリンター。 StoplightのSpectralは、生データとしての有効性を超えてスタイルルールに対応するオープンソースのCLIです。構造的な有効性をチェックし、ルールセットを強制できます。つまり、すべての操作には説明が必要、すべてのスキーマプロパティには型が必要、命名は規約に従う、といったルールです。Spectralは、多くのファイルにわたる仕様のスタイルを管理するためのクラス最高のツールであり、一貫したAPI設計に関心があるなら、採用する価値があります。次のように実行します。
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
トレードオフはスコープです。Spectralはドキュメントを検証し、リンティングします。これはリクエストランナーではないため、仕様が記述するAPIが、仕様が主張する方法で実際に動作するかどうかは教えてくれません。それは別のレイヤーであり、ほとんどのプロダクションでの予期せぬ事態が発生するレイヤーです。
オンラインバリデーターエンドポイント。 Swaggerプロジェクトは、ホストされた仕様URLに対して合格または不合格のバッジを返すバリデーターサービスを公開しています。READMEバッジには便利ですが、インタラクティブな修正ループにはあまり向きません。スタンドアロンオプションについてより深く知りたい場合は、最高のOpenAPIバリデーターツールのまとめと、OpenAPI仕様を検証する方法に関する詳細なチュートリアルを参考にしてください。
これら3つはすべてドキュメントを検証します。しかし、有効な仕様と正しいAPIとの間のギャップを埋めるものはありません。そのギャップが次のセクションの主題です。
Apidogの役割：仕様を検証し、APIがそれに一致することを証明する
ApidogはオールインワンのAPIプラットフォームです。スキーマの設計、リクエストのデバッグ、自動テストシナリオの構築、エンドポイントのモック、ドキュメントの公開を1つのワークスペースで行えます。仕様の検証は、後から追加する独立したツールではなく、プラットフォーム内で作業する際の特性の一部です。
SwaggerまたはOpenAPIファイルをインポートしたり、ビジュアルエディターで設計したりすると、Apidogはそれらを読み込みながら解析し、検証します。不正な形式のドキュメント、壊れた$ref、型のないパラメーターといった問題は、3つの下流ツールでなく、作業中に表面化します。エディターがビジュアルであるため、手書きYAMLの間違いの全カテゴリは発生しません。フィールドが必須のドロップダウンである場合、パラメーターのin値を忘れることはありません。仕様は構築段階で有効になります。
それはドキュメントを処理します。より難しい問題は「ドリフト」です。これは、仕様がAと言っているのにAPIがBを行うという、ゆっくりとした不一致です。スタンドアロンのバリデーターではこれを捕捉できません。ファイル自体は有効だからです。問題は実行中のサービスにあります。これは、非常に多くの乖離するSwaggerドキュメントやPostmanコレクションの背後にある失敗モードです。
Apidogは、仕様をテストの信頼できる唯一の情報源（Source of Truth）とすることで、このギャップを埋めます。OpenAPI仕様から直接テストシナリオを生成し、実際のレスポンスが宣言したスキーマと一致することをアサートします。仕様がageを整数と記述しているのにAPIが文字列を返す場合、テストは失敗します。しかも、手動で保守されたコピーに対してではなく、仕様そのものに対して失敗します。バリデーターの問いは継続的なものになります。「このファイルを保存したときに有効だったか」ではなく、「現在、ライブAPIはその契約に忠実であるか」です。アサーションのメカニズムを知りたい場合は、APIアサーション：実践ガイドで、レスポンスの形状、ステータス、フィールドの検証について解説しています。
検証を記憶しておくのではなく、自動的に強制したいチームのために、Apidogは設計ループの一部としてAPIをOpenAPI標準に準拠させることもサポートしています。
Apidog CLIを使ってCIで仕様駆動型検証を実行する
誰かがエディターを開いたときにのみ実行されるバリデーターは、最終的にはスキップされるバリデーターです。解決策は、検証をパイプラインに組み込み、人間が介在することなくすべてのプッシュで実行されるようにすることです。それこそが、Apidogコマンドラインランナーの目的です。
CLIはapidog-cliというnpmパッケージです。Node.jsがインストールされたあらゆる環境から、Apidogで構築したテストシナリオをヘッドレスで実行します。以下のコマンドでインストールできます。
npm install -g apidog-cli
次に、保存されたシナリオ（ライブレスポンスが仕様に一致することをアサートする同じシナリオ）を環境に対して実行します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
これらのフラグの機能についていくつか説明します。-tはテストシナリオIDです。-eは環境IDで、プルリクエストではステージングに、デプロイ後は本番に同じチェックを適用できます。-rはレポート形式を選択します。読みやすいビルドログ出力にはcliを、CIダッシュボードにフィードするにはhtml、json、またはjunitを追加できます。--access-tokenはCIのシークレットとして設定し、インラインで記述しないでください。トークンと準備されたコマンドは両方とも、Apidog内のシナリオのCI/CDタブから生成できます。完全なフラグオプションについては、apidog run --helpを実行するか、Apidog CLIの完全ガイドをご覧ください。
これを真のゲートとして機能させる重要な詳細があります。アサーションが失敗すると、CLIはゼロ以外のステータスコードで終了します。CIシステムはその終了コードを読み取ります。スキーマチェックの失敗はステップを失敗させ、ジョブを失敗させ、マージをブロックします。そのため、APIがOpenAPI契約と一致しなくなった瞬間に、変更がデプロイされる前（コンシューマーがチケットを提出した後ではなく）に、ビルドが赤くなります。これが、ファイルを一度検証することと、コミットごとに契約を検証することの違いです。同じ終了コードの挙動により、このランナーは、NewmanなしでCIでPostmanコレクションを実行するのと同様に、あらゆるCIプラットフォームに組み込むことができます。
チームがすでにAPIを設計している場所で、仕様検証と契約テストを同じ場所で行いたい場合は、Apidogをダウンロードしてください。
実践的な検証ワークフロー
これらの要素をまとめると、最後の段階だけでなく、あらゆる段階で仕様エラーを捕捉する一連のプロセスは以下の通りです。
- 検証機能付きエディターでの設計またはインポート。 既存のSwaggerファイルをインポートする場合でも、Apidogのビジュアルデザイナーで構築する場合でも、ドキュメントは取り込み時に解析され、構造的に検証されます。壊れた参照や欠落した型はすぐに表面化します。
- ルールセットがある場合はスタイルをリンティングする。 組織が命名規則や説明ルールを強制している場合、Spectralを高速なプレコミットチェックとして実行します。有効性と組織のスタイルは異なる懸念事項ですので、両方をカバーしてください。
- 仕様からテストを生成する。 OpenAPIドキュメントをテストシナリオに変換し、アサーションが出荷する同じ定義に結びつくようにします。乖離する別のコピーではなく。
- CLIでプッシュごとにゲートをかける。
apidog runをパイプラインに組み込み、仕様と現実の不一致が自動的にビルドを失敗させるようにします。 - 仕様を唯一の信頼できる情報源（Source of Truth）として扱う。 設計が変更された場合、テストは同じファイルを指すため、手動で同期を保つ必要はありません。
ステップ1と2はドキュメントを検証します。ステップ3から5は契約を検証します。両方が必要であり、それらすべてを4つのブラウザタブではなく1つのワークスペースで行うのが最も効率的です。
要約
Swaggerバリデーターは、記述時には目に見えず、他の誰かがそれを読み込む際には高くつく、構造的なバグ、壊れた参照、欠落した型、不正な形式のYAMLを捕捉します。ドキュメントの検証は最低限のラインであり、最終目標ではありません。実際にプロダクションに到達するエラーは、有効な仕様が変化するAPIと静かに一致しなくなるものであり、ファイルレベルのバリデーターではそれらを見ることはできません。その解決策は、2つのレイヤーで検証し、両方を1つの場所にまとめることです。つまり、設計時にドキュメントを検証し、次に実際のレスポンスを仕様に対してアサートすることで、すべてのプッシュ時に契約を検証します。Apidogは前者を構築段階で、後者をapidog-cliランナーがCIでゲートするシナリオを通じて行います。仕様は唯一の信頼できる情報源であり続け、現実がそれから乖離した瞬間にビルドは赤くなり、壊れたSwaggerファイルを午後の手遅れになって発見することはなくなります。