Apidog CLIとRedocly CLI 比較：おすすめのAPI CLIは？

これらのツールはどちらもターミナル内で動作し、OpenAPIに対応しており、チームがAPI仕様のコマンドラインワークフローを望む際に登場します。しかし、共通点はそこで終わりです。これらは隣接する問題を逆方向から解決するため、間違ったツールを選ぶと、テストを実行しないリンターと格闘したり、単なる高速な構造チェックが欲しいだけなのにプラットフォームに手を出したりすることになります。

これは、Apidog CLIとRedocly CLIの率直なコマンドレベルの比較です。見せかけの議論はありません。RedoclyのCLIは真に優れたオープンソースソフトウェアであり、判定が下される前にその真価がどこにあるかを確認できます。

TL;DR 結論

これらは重複するが異なる問題を解決します。

Redocly CLI（@redocly/cli、バイナリ redocly）はコードファーストのOpenAPIスペシャリストです。カスタムルールセットでリントし、マルチファイル仕様をバンドルし、分割・結合し、スタンドアロンのHTMLドキュメントを構築します。オープンソースで設定駆動型、ターミナルネイティブです。もしあなたの仕様が唯一の真実でありGitに存在する場合、これはコマンドラインから実行するガバナンスツールです。

Apidog CLI（apidog-cli、バイナリ apidog）はオールインワンAPIプラットフォームのコマンドラインインターフェースです。プロジェクトに対して定義をインポートおよびエクスポートし、CIでJUnitおよびHTMLレポートと共にAPIテストシナリオを実行します。同じ仕様が個別のツールを組み合わせて使用するのではなく、1つのワークスペースでモック、テスト、ドキュメント化される必要がある場合にその価値を発揮します。

軽量なオープンソースのリンター、バンドラー、ドキュメントビルダーを純粋にターミナルから実行したい場合はRedocly CLIを選びましょう。APIライフサイクル全体を1つのツールで管理したい場合はApidogを選びましょう。これらは並行して機能することも可能で、最後のセクションでその方法を説明します。

2つの異なる哲学

Redocly CLIはファイル中心でコードファーストです。ディスク上のOpenAPIドキュメントが操作対象となります。redocly lint、redocly bundle、redocly build-docsなど、すべてのコマンドはファイルへのパスを受け取り、アカウントやサーバーを介さずにローカルで処理を実行します。動作は、仕様の隣にリポジトリにチェックインするredocly.yaml設定によって決定されます。このモデルは、API記述をソースコードとして扱うチームに適しています。つまり、プルリクエストでレビューされ、CIでゲートされ、他のすべてと同じようにバージョン管理されます。OpenAPI Specificationが契約であり、Redocly CLIはそれを管理するツールチェーンです。

Apidogはプロジェクト中心でプラットフォームファーストです。デスクトップまたはウェブアプリでエンドポイントを設計し、モックサーバーを構築し、テストシナリオを視覚的に作成し、CLIはその作業の一部をヘッドレスで実行するインターフェースです。ほとんどのCLIコマンドは、プロジェクトIDで識別されアクセストークンで認証されたサーバー上のApidogプロジェクトに対して動作します。仕様は単にリントするファイルではなく、モック、テスト、ドキュメントとして公開できるライブワークスペースにインポートされます。1つの環境で多くのジョブを実行します。

どちらの哲学も間違いではありません。それぞれ異なるチームに適しています。正直な違いは次のとおりです。Redoclyは仕様ガバナンスのための集中的なオープンソースCLIを提供し、Apidogはより広範なプラットフォームへのCLIを提供します。

コマンドごとの比較

重要な部分をタスクごとにマッピングしました。以下のすべてのコマンドは実在し、架空のものは含まれていません。

これらの行のいくつかについては、違いが明確であり、それを隠すことはこの記事にとって不誠実であるため、率直な注釈を付ける価値があります。

リントはApidogの領分ではなく、Redoclyの得意分野です。 Redocly CLIは、設定可能なルールセットに対してOpenAPI、AsyncAPI、Arazzo、およびOpen-RPCをリントし、独自のルールを作成できます。Apidogは定義をインポートする際に構造を検証しますが、apidog lint、redocly.yaml形式の設定、およびCLIを通じてカスタムスタイルガイドルールを記述する方法はありません。目的がターミナルで適用されるコードファーストのスタイルガイドである場合、Redoclyがそのツールです。Apidogはここで競合せず、そう言うのは間違いでしょう。

分割と結合はRedoclyのものです。 redocly splitは1つの記述をマルチファイル構造に展開し、redocly join（実験的）は複数のファイルを1つにマージします。Apidogにはどちらのコマンドもありません。そのインポート機能はマルチファイルの$refを統一されたリソースに解決し、エクスポート機能は単一の統合ファイルを出力しますが、これは独立した分割/結合ユーティリティとしてバラバラのファイルに対して実行するのとは異なります。

テスト実行とモックはApidogのものです。 Redocly CLIはAPIテストを実行せず、モックサーバーもホストしません。これは設計上、その範囲外です。Apidogはapidog runでテストシナリオをヘッドレスで実行し、パイプライン用のJUnit、HTML、JSON、およびCLIレポートを生成します。また、モックはプラットフォームの第一級機能です（アプリ内で作成され、CLIから駆動されるものではありません）。

どちらもターミナルからHTMLドキュメントをビルドします。 redocly build-docsはスタンドアロンのRedoc HTMLファイルを生成します。apidog export --format htmlはプロジェクトからHTMLドキュメントファイルを作成します。異なるエンジンですが、ターミナルでの結果は同じです。

実際のRedocly CLIコマンド

グローバルにインストールするか、インストールをスキップしてnpx経由で実行します。

npm install -g @redocly/cli@latest
# または、グローバルインストールなし:
npx @redocly/cli@latest lint openapi.yaml

仕様をリントします。redocly.yamlが存在する場合、これは選択したルールセット（minimal、recommended、recommended-strict、spec、またはカスタムルール）を適用します。

redocly lint openapi.yaml

廃止されたswagger-cliがかつて行っていたような、単純な構造検証のみが必要な場合は、redocly.yamlをspecルールのみで設定し、同じredocly lintを実行します。RedoclyはRedocly CLIがその後継であるため、swagger-cliからの移行ガイドを公開しています。同じ理由で、swagger-cliのリポジトリには現在、廃止通知が掲載されています。この古いツールは、スタイルルールでリントすることはなく、検証とバンドルしか行いませんでした。

すべての$refをたどって、マルチファイル定義を1つのファイルにバンドルします。

redocly bundle openapi.yaml --output bundled.json

swagger-cliから移行する場合、フラグはきれいにマッピングされます。-o/--outfileは--outputに、-t/--typeは--ext（json、yaml、またはyml）に、-r/--dereferenceは-d/--dereferencedになります。

RedocでスタンドアロンのHTMLドキュメントを構築します。

redocly build-docs openapi.yaml -o docs.html

1つの記述をマルチファイルレイアウトに分割します。これはバンドルの逆です。

redocly split openapi.yaml --outDir ./split-spec

このカテゴリの他のツールとのRedoclyの比較については、OpenAPIリンターセットアップガイドでSpectral、Redocly、Vacuumが並べて紹介されており、Redoclyの代替ツールではドキュメントプラットフォームに特化して紹介されています。

実際のApidog CLIコマンド

CLIをインストールし、アプリからトークンで認証します（アバター、次にアカウント設定、次にAPIアクセストークン）。

npm install -g apidog-cli@latest
apidog login --with-token <TOKEN>

トークンは~/.apidog/config.tomlに保存されます。表示したりコミットしたりしないでください。

定義をプロジェクトにインポートします。これにより、構造が検証され、マルチファイルの$refが統一されたリソースに解決されて取り込まれます。

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

インポートはOpenAPIだけでなく、Postman、HAR、Insomnia、JMeter、WSDL、YApi、RAP2、apiDoc、Hoppscotch、Markdown、JSON Schema、およびApidog独自の形式にも対応しています。

単一の統合ファイルをエクスポートし、オプションでOpenAPIバージョンをアップグレードします。これは、バンドルとオプションのバージョンアップグレードを1つのステップで行うものです。

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

プロジェクトから直接HTMLドキュメントをエクスポートします。

apidog export --project 123456 --format html --output ./docs.html

CIでテストシナリオを実行し、パイプラインが読み取れるレポートを出力します。

apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"

エクスポートされたコレクションファイルから完全にオフラインで実行することも可能です。プロジェクトやトークンは不要です。

apidog run ./collection.apidog-cli.json

--out-dir、-n/--iteration-count、-d/--iteration-data、--env-varを含む完全なフラグ参照は、Apidog CLI完全ガイドにあります。公式のApidog CLIドキュメントでは、インストールとすべてのリソースコマンドが説明されています。ランナーごとのCI比較については、Apidog CLI vs NewmanとBruno CLI vs Apidog CLIを参照してください。

Redocly CLIを選ぶべき時

仕様が唯一の真実であり、それをコードとして管理したい場合は、Redocly CLIを選びましょう。

カスタムルールを持つ真のリント機能が欲しい場合。Redoclyのlintコマンドとredocly.yaml設定は、その特徴的な機能です。組み込みのルールセットを選択するか、独自のルールを作成して、コミットごとに命名規則、必須フィールド、ハウススタイルを適用します。ApidogのCLIにはこれに匹敵するものはありません。ターミナルネイティブのスタイルガバナンスが目的であれば、Redoclyが答えです。

アカウント不要のオープンソースが欲しい場合。CLIは完全にあなたのマシンまたはCIランナー上で動作します。lint、bundle、split、build-docsのいずれのコマンドでもログイン、トークン、サーバーへの呼び出しは必要ありません。エアギャップ環境や厳格なデータ処理ルールがある場合、Redoclyはそれを満たす厳しい要件であり、プラットフォームCLIでは一般的に満たされません。

軽量で集中的なツールチェーンが欲しい場合。ターミナルからリント、バンドル、分割、結合、HTMLドキュメント作成のみが必要な場合、Redoclyはまさにそれを行い、それ以上は行いません。インストールまたはnpxを介して、ゼロセットアップで実行できます。完全なコマンドセットはRedocly CLIドキュメントとnpmパッケージページにあります。

Apidogを選ぶべき時

設計、モック、テスト、ドキュメントといったAPIライフサイクル全体を、個別のツールを組み立てるのではなく、一元的に管理したい場合はApidogを選びましょう。

デザイン、モック、テスト、ドキュメントをすべて一箇所で管理したい場合。CLIはあなたの仕様をインポートし、選択したOpenAPIバージョンでクリーンな統合ファイルをエクスポートし、CIでテストシナリオを実行します。同じプロジェクトで、視覚的なデザイン、モックサーバー、公開されたドキュメントも利用でき、すべてが1つの定義を共有します。リンター、モックツール、テストランナー、ドキュメントジェネレーターを組み合わせて使う必要がなくなります。

パイプラインで利用可能なレポート付きでテストを実行したい場合。apidog runはCIダッシュボード用のJUnit XML、HTMLおよびJSONアーティファクトを生成し、テストが失敗した場合は非ゼロで終了します。Redoclyはテストを一切実行しないため、CIテストゲートがリストにある場合、Apidogが適しています。CIでのOpenAPIバリデーションのパターンは、同じパイプラインでのテスト実行と自然に連携します。

チーム全体で唯一の真実となる情報源が必要な場合。リソースはApidogプロジェクト内に存在し、デザイナー、テスター、ライター全員がそこから作業します。CLIは共有ワークスペース上の自動化インターフェースであり、仕様ファイルをやり取りするよりもプラットフォームで共同作業することを好むチームに適しています。

利用を開始するにはApidogをダウンロードしてください。無料で開始でき、クレジットカードは不要です。

これらは相補的でありうる

これは厳密に「どちらか一方」というわけではなく、そうだと主張するのは最も実用的なセットアップを見逃すことになります。

強力なワークフローは、Redocly CLI（またはSpectral）をCIのリンゲートとして実行し、すべてのプルリクエストでスタイルガイドを強制し、Apidogを設計、モック、テスト実行、および公開ドキュメントに使用します。オープンソースのルールセットを使用してターミナルでリントを最適に行い、プラットフォームが最適な場所でモック、テスト、ドキュメントを作成します。仕様はこれらツールの間を流れます。CIでファイルをリントし、下流のすべてのプロセスでApidogにインポートします。

この組み合わせは、一方に他方の仕事を無理強いするのではなく、各ツールの実際の強みを活かします。

FAQ

Apidog CLIにはRedoclyのようなカスタムルールを持つリントコマンドがありますか？

ありません。Apidogは定義をインポートする際に構造を検証しますが、apidog lintコマンドやCLIを通じてカスタムスタイルガイドルールを作成する方法はありません。設定可能なコードファーストのリントには、Redocly CLIまたはSpectralを使用してください。

Redocly CLIはCIでAPIテストを実行できますか？

いいえ。Redocly CLIはリント、バンドル、分割、結合、ドキュメントのビルドを行います。APIテストを実行したり、モックサーバーをホストしたりすることはありません。JUnitおよびHTMLレポートによるヘッドレステスト実行には、apidog runを使用してください。

ApidogはRedocly CLIのようにオープンソースですか？

いいえ。Redocly CLIとSpectralはオープンソースです。Apidogはフリーミアムです。CLIはnpmから無料でインストールできますが、完全にオープンソースのソフトウェアとしてではなく、Apidogアカウントとプロジェクトに対して動作します。

swagger-cliで検証とバンドルをしていました。何に移行すべきですか？

どちらのツールも対応しています。Redocly CLIはswagger-cliの後継であり、redocly lint（単純な検証にはspecルールを設定）とredocly bundleを備えています。Apidogは、apidog import（検証）とapidog export（バンドル、オプションでOpenAPIバージョンアップグレード付き）を通じて同じ機能を提供し、モック、テスト、ドキュメントを同じワークスペースに追加します。