Dreddを使わないAPI仕様検証の方法

Dreddは実際の問題を解決し、それをきれいに解決します。API記述、OpenAPIドキュメント、またはAPI Blueprintファイルを指定し、稼働中のサーバーに向けます。記述内のすべての例を読み取り、対応するリクエストをライブバックエンドに送信し、実際のリスポンスが仕様で約束されたものと一致するかどうかを確認します。もし仕様がGET /orders/{id}がidとstatusフィールドを含む200を返すと記述している場合、Dreddは実行中のサービスが実際にそれを行っていることを確認します。仕様は静かに陳腐化するドキュメントではなく、大音響で失敗するテストになります。

実装をAPI記述に対して検証するというその考え方は、正しい考え方です。仕様が述べる内容とサービスが行う内容との間のずれは、API作業における最もコストのかかるサイレントバグの一つです。フロントエンドチームはドキュメント化された契約に基づいてコードを書き、バックエンドはフィールド名を変更し、誰もドキュメントを更新せず、本番環境で問題が表面化します。Dreddはまさにそのような種類の障害を捉え、長年にわたり、コマンドラインからそれを行うための頼りになるオープンソースツールでした。

摩擦は概念ではなく、セットアップと維持にあります。Dreddは独自の構成ファイル、些細なケースを超えたあらゆることのための選択言語でのフックファイル、そして他のすべてと一緒に手作業で維持する別の仕様成果物を必要とするNode.js CLIです。Dreddが提供するのと同じ結果、つまり実装がOpenAPI契約と一致しなくなったときに失敗するCIゲートを、フックツールチェーンを立ち上げることなく、また仕様をサードパーティの切り離されたファイルとして保持することなく得たいのであれば、Apidogはそのワークフローのために構築されています。それは仕様、テスト、検証を一つのプロジェクトに保持し、npm CLIから全体をヘッドレスで実行します。このガイドは、Dreddが優れている点について公正であり、統合されたパスが勝る点について明確です。

Dreddが優れている点

Dreddに正当な評価を先に与えましょう。なぜなら、その評判を築き上げたからです。

モックではなく、実装をテストする。 これが核心です。多くのツールはOpenAPIファイルが適切に形成されているか、モックサーバーが動作するかを検証します。Dreddはより困難なことを行います。それは実際に実行中のバックエンドにヒットし、返ってくる実際のバイトをドキュメント化された例と照合します。Dreddの実行が成功するということは、デプロイされたサービスと仕様が理論上ではなく、今、一致していることを意味します。

API BlueprintとOpenAPIの両方に対応している。 Dreddはマークダウンベースの記述形式であるAPI Blueprintと共に成長し、後にOpenAPI 2および3のサポートを追加しました。もしレガシーなBlueprintファイルやSwaggerドキュメントをお持ちの場合、Dreddは変換ステップなしでそれを読み取ることができます。

言語に依存しないフック。 デフォルトのリクエストと比較のループだけでは不十分な場合、認証トークンが必要な場合、テスト前にデータベースをシードする必要がある場合、トランザクションをスキップする必要がある場合、Dreddはフックを記述することを可能にします。フックハンドラはデフォルトでNodeで実行されますが、DreddはPython、Ruby、Go、PHP、Rustなどでのフックのプロトコルサポートを提供しています。チームは既に知っている言語でセットアップロジックを記述できます。

オープンソースであり、CIフレンドリーである。 Dreddはnpm install -g dreddでインストールでき、単一のコマンドとして実行され、検証が失敗するとゼロ以外のコードで終了するため、あらゆるCIシステムがビルドをゲートできます。SaaSアカウントも、シート料金も、サインアップも不要です。セルフホスト型でスクリプト可能な契約チェックを望むチームにとって、それは重要です。

これらは何も無駄ではありません。Dreddは明確な役割を持つ堅実なツールです。問題は、そのモデル、つまり3つの別々の成果物とフックファイルが、実際にあなたが作業したい方法と一致するかどうかです。

摩擦が生じる場所

Dreddのモデルには3つのコストが伴い、その影響はセットアップによって異なります。

仕様は手動で維持する3番目の成果物である。 Dreddは記述ファイルに対して実装を検証します。これはまさに正しいのですが、その記述は通常、APIを設計しテストする場所とは別に存在します。openapi.yamlを手動で編集し、テストシナリオは別の場所に置き、実行中のサービスはさらに別の場所に置きます。Dreddはこれら3つのうち2つを互いにチェックします。仕様自体を正確に保つことは依然として手動の作業であり、現実から静かに乖離した仕様は、グリーンだが間違っているDreddの実行結果を生成します。

フックは記述し維持するコードである。 APIが認証、順序付け、またはテストデータを必要とする瞬間、例駆動型ループだけでは不十分になります。hooks.js（またはPythonやRubyの同等物）を記述し、dredd.ymlを通じて接続すると、最初のコードベースをテスト可能にするためだけの2番目のコードベースを所有することになります。シンプルな読み取り専用APIの場合、Dreddはほとんど設定不要です。ログインとステートフルなエンドポイントを持つ実際のAPIの場合、フックファイルは増大し、それは別の名前のグルーコードです。

例駆動型のカバレッジにはギャップがある。 Dreddは記述に存在する例をテストします。エンドポイントに1つのドキュメント化された例のレスポンスがある場合、それがチェックされます。仕様に例として明記されていないエッジケース、エラーパス、検証ルールは、仕様を拡張するか、より多くのフックを記述しない限り実行されません。カバレッジは、あなたが維持する例と同じくらい良く、それ以上ではありません。

統合されたパス：一つのプロジェクトにおける仕様とテスト

Apidogが採用する異なるアプローチを紹介します。API定義は手動で同期する3番目のファイルではありません。それは、それを実行するテストとビルドをゲートする検証と同じプロジェクトに存在する、信頼できる情報源です。スキーマを変更すると、テストは新しい形状を認識します。リポジトリの隅で乖離していく個別のopenapi.yamlもなく、仕様と機能するテストの間に立つフックファイルもありません。

APIの設計またはインポートは一度だけ行います。ApidogはOpenAPI 2および3を読み込み、Swaggerドキュメントをインポートし、ワンクリックでPostmanコレクションを取り込みます。エンドポイント、リクエストスキーマ、レスポンススキーマ、および例のレスポンスはすべて1つのプロジェクトにまとめられます。もしあなたがすでにスペックファーストで考えているなら、これはDreddが推奨するのと同じ規律ですが、スペックがばらばらのファイルではないという点が異なります。このワークフローのより深いバージョンはスペックファーストのAPI開発にあり、テスト実行前にスペックドキュメント自体を検証したい場合は、OpenAPIスペックの検証でそのステップがカバーされています。

これらの実際のスキーマに対して検証を構築します。テストシナリオがGET /orders/{id}を呼び出すとき、Apidogがそのエンドポイントのために既に保持しているスキーマに対してレスポンスをアサートし、手作業でコピーされた例に対してではありません。これはDreddが実行するスペック対実装のチェックですが、1つの違いがあります。チェックされるスペックは、APIを設計したのと同じオブジェクトであるため、テストスイートと静かに乖離することはありません。これは3番目の成果物なしの契約テストであり、この規律のより広い全体像を知りたい場合は、API契約テストと双方向契約テストの両方がより深く掘り下げています。

Dreddがフックファイルで処理するセットアップ、認証トークン、順序付け、シードなどは、JavaScriptでのリクエスト前およびリクエスト後スクリプトで処理します。これはほとんどのWeb開発者が既に記述しているものです。設定ファイルを通じて接続された別のフックコードベースはありません。ロジックはそれがサポートするテストの隣に存在します。

Apidog CLIのインストールと実行

ランナーはapidog-cliとしてnpmに公開されています。Node.jsがあれば、必要なものはすべて揃っています。

npm install -g apidog-cli

バイナリはapidogなので、すべての実行はapidog runから始まります。テストシナリオを実行するには、アクセストークン、シナリオID、環境IDを渡します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

これらのIDを手動で入力する必要はありません。Apidogでテストシナリオを開き、CI/CDタブに移動し、コマンドラインオプションを選択してアクセストークンを生成します。Apidogは、シナリオと環境IDがすでに埋められた完全なapidog runコマンドを自動生成します。一度コピーし、そこからトークンをパラメーター化してください。アクセストークンはパスワードのように扱ってください。CIシステムにシークレットとして保存し、ここにあるすべての例のように$APIDOG_ACCESS_TOKENとして参照してください。

複数のシナリオを実行するには、単一のIDの代わりにフォルダーまたはテストスイートをランナーに指定し、レポーターを選択します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports

この-rフラグはレポーターを選択します。Apidogは、読みやすいターミナル出力用のcli、ビルド成果物としてアーカイブする自己完結型レポート用のhtml、ほぼすべてのCIダッシュボードが合否ツリーに解析するXML用のjunit、および生の構造化結果用のjsonをサポートしています。ランナーのより詳細なツアーが必要な場合は、apidog run --helpを実行して全フラグリストを確認してください。

比較表

この表を正直に読んでください。もし完全にセルフホスト型で、オープンソースで、アカウント不要のツールを望み、チームがフックファイルの維持に慣れているのであれば、Dreddのモデルはきれいに適合し、それ自体を切り替えることに何もメリットはありません。統合されたパスのケースは具体的です。つまり、スペックが乖離する3番目のファイルであることにうんざりしている、フックコードベースを所有したくない、または同じプロジェクトで設計、テスト、契約チェックをまとめて処理したい場合です。

CIへの組み込み

Apidog CLIは、成功時にはゼロを、失敗時にはゼロ以外のコードで終了するため、Dreddと全く同じように、あらゆるCIシステムがビルドをゲートできます。最小限のGitHub ActionsジョブにはNodeと1つの実行ステップが必要です。

name: api-contract-check
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

これがパイプライン全体です。Dreddのジョブも同様で、CLIをインストールし、1つのコマンドを実行しますが、スペックファイルとフックファイルも指定し、両方を常に最新の状態に保つ必要があります。検証は同じ方法で実行されます。違いは、そこに到達するためにいくつの成果物を維持するかです。

Dreddに手を伸ばす理由が、スペックとサービスを互いに正直に保つことにあるのであれば、同じロジックが他のツールにも現れます。OpenAPI駆動型テストがSwaggerとPostmanの乖離をカバーするように、チームはSwaggerとPostmanの乖離に直面します。また、JavaショップではRest Assuredでこれに直面し、代替案の話は似ています。つまり、そのモデルが望ましくないレイヤーを追加する強力なツールです。IDEを離れたくない場合は、VS Code拡張機能でエディタからApidogを操作することもできます。

FAQ

ApidogはDreddセットアップのドロップイン代替品ですか？ いいえ、そう自称していません。dredd.ymlとhooks.jsを読み取り、Apidogシナリオを生成するコンバーターはありません。OpenAPIスペックをインポートし、ビジュアルエディターで検証を再構築します。利点は、フックファイルとばらばらのスペックの維持をやめることです。コストは1回限りの再構築です。もし大規模で成熟したDreddスイートが機能している場合、その再構築は、ただの「ただ乗り」ではなく、現実的な決断となります。

ApidogはDreddのようにライブ実装を検証しますか？ はい。CLIは実行中のサービスに実際のリクエストを送信し、プロジェクト内のスキーマに対して実際のリスポンスをアサートします。これはDreddが実行するのと同じスペック対実装のチェックです。違いは、チェックされるスキーマがAPIを設計した元のスキーマであるため、テストから乖離しないことです。

Dreddのフックでできたように、認証やテストのセットアップはまだできますか？ はい。ApidogはJavaScriptでのリクエスト前およびリクエスト後スクリプトをサポートしているため、認証トークンの取得、データのシード、ペイロードの変換、コードでの動的なアサーションの構築が可能です。ロジックは、設定を通じて接続された個別のフックファイルではなく、それがサポートするシナリオ内に存在します。

DreddがApidogにはできないことはありますか？ いくつかあります。Dreddは完全にセルフホスト型でオープンソースであり、アカウントは不要です。また、古いマークダウン記述形式であるAPI Blueprintをネイティブで読み取ります。もしアカウント不要の完全にローカルなツールやレガシーなBlueprintファイルがセットアップの中心である場合、切り替える前によく検討してください。

Apidogはどの形式を読み取りますか？ OpenAPI 2と3、Swaggerドキュメント、およびPostmanコレクションをすべて1つのプロジェクトにインポートできます。もし形式の違いを最初に理解したい場合は、Swagger対OpenAPIとOpenAPI仕様の概要の両方がそれらを説明しています。

結論

Dreddは核心となるアイデアを正しく捉えました。つまり、API記述は、乖離するドキュメントではなく、実行中のサービスをテストするためのものであるべきだということです。もしセルフホスト型でオープンソースのCLIを望み、スペックファイルとフックファイルの維持に満足しているのであれば、Dreddは堅実な選択であり、使い続けるべきです。

統合されたパスは、その維持作業をなくしたい場合に適しています。Apidogは、スペック、テスト、検証を1つのプロジェクトに保持するため、チェックする契約は設計されたものと同じであり、apidog runからフックコードベースを所有することなく全体を実行します。Apidogをダウンロードし、既存のOpenAPIファイルをインポートして、単一のコマンドからスペック対実装のチェックが実行される様子を確認してください。