Swagger CLIからApidog CLIへの移行方法

パイプラインでまだswagger-cli validateやswagger-cli bundleを実行している場合、それは誰もメンテナンスしていないツールのスクリプトを維持していることになります。swagger-cliのGitHubリポジトリでは現在、パッケージがもはやメンテナンスされていないこと、READMEが貢献の少ない巨大なユーザーベースに対応する負担を挙げていること、そして新しいユーザーを別の場所へ案内していることが明記されています。

したがって、これはあなたのスペックワークフローが次にどこに落ち着くかを決める良い機会です。このガイドは移行のランブックであり、使用チュートリアルではありません。移行する準備ができておらず、古いツールを使い続けたいだけであれば、Swagger CLIガイドがvalidateとbundleについて詳しく解説しています。この記事は、具体的にSwagger CLIからApidog CLIへの移行方法について、CIを壊さずに説明します。

実際のコマンドを試したい場合は、Apidogをダウンロードしてください。無料で開始でき、クレジットカードは不要です。

ボタン

今すぐ移行する理由

まず正直な答えから：swagger-cliはしばらくの間非推奨であり、メンテナンスされていません。まだ動作します。今日でも多くのパイプラインがそれを呼び出しています。しかし、バグ修正や仕様更新が行われないツールは、ビルドに技術的負債として残っており、メンテナー自身が移行を推奨しています。

彼らは特に一つの後継ツールを指名しています。ターミナルでバリデートとバンドルだけを望むのであれば、Redocly CLIが最も近いドロップインの代替品です。これはオープンソースで、コードファースト、ターミナルネイティブです。そのlintコマンドは構造的なバリデーションを行い、redocly bundleはswagger-cli bundleと同じように$refポインタを追跡します。もし、リポジトリにスペックを単一ファイルとして保持する1対1の入れ替えだけが目標であれば、Redoclyが自然な選択であり、Redoclyは独自の移行ガイドをコマンドマッピングとともに公開しています。その道を選ぶことに何の恥もありません。

Apidogは別の目標のためのものです。スペックをファイルに置いておくだけでなく、もっと活用したいときにApidog CLIに移行します。静的なドキュメントをバリデートしてバンドルする代わりに、定義全体をライブのワークスペースに取り込み、インポート時にバリデートし、必要なときに統合されたファイルをエクスポートし、オプションでAPIをモックし、テストシナリオを実行し、同じソースからドキュメントを公開します。swagger-cliは常に2つのことしかできませんでした。Apidogはライフサイクルの残りの部分をカバーします。

バズワードではなく、適合性に基づいて選択してください。軽量で設定駆動のリンターとバンドラーを純粋にターミナルから実行したい場合は、Redoclyが優れています。複数のツールを組み合わせるのではなく、設計、モック、テスト、ドキュメント作成のための単一プラットフォームが欲しい場合は、Apidogが優れています。

swagger-cliが行ったこと vs Apidog CLIが行うこと

swagger-cliには正確に2つのコマンドがありました：

swagger-cli validate <file>はSwagger 2.0またはOpenAPI 3.0ドキュメントをスキーマに対してチェックし、その$refポインタが解決されることを検証しました。
swagger-cli bundle <file>はそれらの$refポインタを追跡し、複数ファイルの定義を単一ファイルに結合しました。出力パス(-o)、タイプ(-t json|yaml)、完全なデリファレンス(-r)、インデント(-f)のオプションがありました。

それがツール全体です。スタイルルールでのリンティング、ドキュメントの生成、テストの実行、モックは一切行いませんでした。

Apidog CLIはこれら2つのタスクを2つのコマンドにマッピングし、さらに以下の機能を提供します：

apidog importは定義をApidogプロジェクトに取り込み、取り込み時に検証します。複数ファイルのスペックは、その$refポインタが自動的に統一されたリソースに解決されます。これはあなたのバリデートステップであり、取り込みも含まれます。
apidog exportはプロジェクトから単一の統合されたファイルを出力し、出力時にOpenAPIバージョンを選択できます。これはあなたのバンドルステップであり、オプションのバージョンアップグレードとHTMLまたはMarkdownドキュメントの出力機能も含まれます。
apidog runはテストシナリオとスイートを実行し、CI用のJUnitや他のレポーターを提供します。swagger-cliには同等の機能はありませんでした。
リソースコマンド(endpoint、schema、mock、environment、branchなど)は、スペックが取り込まれた後にターミナルからプロジェクトを管理します。

マッピングを正直に保つための正確な点：Apidogはインポート時に構造を検証しますが、設定可能なスタイルガイドリンターではありません。apidog lintコマンドやカスタムルールセットはありません。もし意見のあるリンティングに依存していた場合、その部分は引き継がれません。バリデートとバンドルを超えて得られるもののセクションで、その対処法を説明しています。

インストールとログイン

Apidog CLIはnpmパッケージとして提供されます。グローバルにインストールします：

npm install -g apidog-cli@latest

次に、アクセストークンで認証します：

apidog login --with-token <TOKEN>

トークンはApidogアプリまたはウェブから取得できます。「アバター」をクリックし、「アカウント設定」に進み、「APIアクセストークン」で生成します。CLIはそれを~/.apidog/config.tomlに保存します。他のシークレットと同様に扱ってください。ログに表示したり、リポジトリにコミットしたりしないでください。

すべてのフラグとより詳細な説明が必要な場合は、Apidog CLI完全ガイドと公式Apidog CLIドキュメントで全体をカバーしています。この移行のためには、インストールとログインだけで開始できます。

コマンドマッピング表

以下は、swagger-cliからApidog CLIへの直接的な変換です。構造上の唯一の違いは、Apidogがプロジェクトに対して動作するため、ほとんどのフローは単一のファイルに対する単一のコマンドではなく、インポートしてからエクスポートという形になります。

swagger-cli コマンド	Apidog CLI 同等コマンド	変更点
`swagger-cli validate openapi.yaml`	`apidog import --project <id> --format openapi --file ./openapi.yaml`	インポート時にスペックを検証します。無効なスペックはコマンドを失敗させます。
`swagger-cli bundle openapi.yaml -o out.json`	`apidog import ...` の後 `apidog export --project <id> --format openapi --output ./out.json`	バンドルはプロジェクトからのエクスポートになります。`$refs`はインポート時に既に解決されています。
`swagger-cli bundle -t yaml`	`apidog export --project <id> --format openapi --output ./out.yaml`	出力フォーマットは書き込むファイルに従います。
（同等なし）	`apidog export --project <id> --format openapi --output ./out.json --oas-version 3.1`	2.0または3.0のスペックをエクスポート時に3.1にアップグレードします。
（同等なし）	`apidog export --project <id> --format html --output ./docs.html`	スタンドアロンのHTMLドキュメントを出力します。
（同等なし）	`apidog export --project <id> --format markdown --output ./docs.md`	Markdownドキュメントを出力します。
（同等なし）	`apidog run --project <id> -t <scenarioId> -e <envId> -r junit`	CIでAPIテストを実行します。

移行にとって最も重要な2つのセルは、最初の2行です。それ以下のすべては、swagger-cliにはなかった機能です。--oas-versionフラグは最も明確なアップグレードです。swagger-cliはSwagger 2.0ファイルをバンドルできましたが、OpenAPI 3.1に変換することはできませんでした。Apidogはエクスポート時にそれが可能であり、古い契約を最新化する際に便利です。もしドキュメント出力が特定の目標であれば、OpenAPIをMarkdownにエクスポートする方法がそのフォーマットについてより詳しく解説しています。

ステップバイステップの移行

ここでは、swagger-cliのセットアップからApidogの動作フローへの完全なパスを示します。

1. プロジェクトIDを取得します。 Apidogアプリでプロジェクトを作成または開きます。プロジェクトIDはプロジェクト設定とURLに表示されます。これを--projectを介してすべてのCLIコマンドに渡します。

2. ルートスペックをインポートします。 定義のエントリファイルをApidogに指定します。$refポインタを持つ複数ファイルのスペックは自動的に解決されるため、ルートをインポートすればApidogが残りをプルインします：

apidog import --project 123456 --format openapi --file ./openapi.yaml

スペックが不正な形式であるか、$refが未解決の場合、インポートは失敗します。その失敗があなたのバリデーションゲートであり、swagger-cli validateがかつて行っていたのと同じジョブが、取り込みに組み込まれています。

3. アプリで確認します。 プロジェクトを開き、エンドポイント、スキーマ、パラメータが正しくインポートされていることを確認します。この視覚的なチェックはswagger-cliには同等の機能がなく、移行中にインポートが期待通りに行われたかを確認する価値があります。

4. 統合されたファイルをエクスポートします。 単一のフラットファイル（下流のツール、クライアントジェネレーター、または成果物用）が必要な場合は、それをエクスポートします。必要なOpenAPIバージョンを選択します：

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

これはswagger-cli bundleに代わるものです。$refポインタはインポート時に既に解決されているため、エクスポートはあなたの統合された単一ファイルの出力となります。

5. CIに組み込みます。 古いswagger-cliステップをインポート（取り込み時に検証）とエクスポート（バンドル）に置き換え、シナリオがある場合はテスト実行を追加します。次のセクションでは、GitHub Actionsの完全な例を示します。

GitHub ActionsでのCI例

このワークフローは、CLIをインストールし、リポジトリシークレットからのトークンでログインし、スペックをインポートして検証し、統合された成果物をエクスポートし、その後JUnitレポーターを使用してテストシナリオを実行します。これにより、テストが失敗した場合にチェックが失敗し、PRがマージをブロックされます。

name: API spec check

on:
  pull_request:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

トークンはリポジトリのシークレットとしてAPIDOG_ACCESS_TOKENに保存してください。これによりログに表示されることはありません。-r "cli,junit"レポーターはJUnit XMLファイルを書き込み、CIがそれをテストレポートとして表示できます。失敗したシナリオはゼロ以外の終了コードを返し、マージをブロックします。より詳細なパイプラインパターンについては、Apidog CLI CI/CDガイドを、ランナー固有のセットアップについてはGitHub ActionsでのApidog CLIのウォークスルーを参照してください。

バリデートとバンドルを超えて得られるもの

ここが移行の報われる部分であり、正直さが最も重要となる部分です。

モックサーバー。 スペックがプロジェクトに取り込まれると、Apidogはそれからモック応答を提供できます。バックエンドが存在する前に、APIに対してフロントエンドを開発できます。swagger-cliはランタイムの振る舞いを一切扱いませんでした。

自動テストシナリオ。 apidog runは、実行中のAPIに対して実際のリクエストを実行し、応答をアサートします。アプリでシナリオを視覚的に構築し、CIでヘッドレスに実行します。これにより、swagger-cliが大きく開けていたギャップが埋まります。有効なスペックは契約が適切に形成されていることを示しますが、実装がそれに一致することを示すものではありません。

ホストされたドキュメントとエクスポートされたドキュメント。 apidog export --format htmlまたは--format markdownは、同じソースから直接ドキュメントを生成します。別途ドキュメント構築ステップを維持する必要はありません。

ここで正直な限界を述べます。Apidog CLIには、設定可能なコードファーストのスタイルガイドリンターとカスタムルールセットはありません。インポート時に構造を検証しますが、CLIを介してSpectralスタイルまたはRedoclyスタイルのルールを作成することはできず、apidog lintコマンドもありません。古いセットアップで厳格なリンティング（一貫した命名、必須の記述、すべての応答の例など）に依存していた場合は、専用のリンターを引き続き使用してください。ApidogをSpectralまたはRedoclyと組み合わせて、それを別のCIステップとして実行します。OpenAPIリンターセットアップガイドでは、それをどのように組み込むかについて説明しています。両方を使用することは矛盾ではありません。専門ツールでリンティングを行い、Apidogでライフサイクルを管理します。

ボタン