DEV Community

Cover image for API連携におすすめの軽量CLIツール
Akira
Akira

Posted on • Originally published at apidog.com

API連携におすすめの軽量CLIツール

APIコラボレーションは、重いアプリを起動して同期を待ち、パネルを操作して変更内容を確認する作業だと思われがちです。しかし、APIがOpenAPIファイルで管理されているなら、コラボレーションの大半はテキストベースで完結します。仕様のバージョン管理、差分レビュー、共有変更のマージを、ターミナルとCIで実行できます。

今すぐApidogを試す

このガイドでは、APIコラボレーションでよく必要になる次の3つの作業をCLIで扱う方法を紹介します。

  1. 仕様のバージョン管理：誰がどの仕様を使っているかを追跡する
  2. 変更のレビュー：何が変わり、破壊的変更がないかを確認する
  3. 共有変更のマージ：レビュー済みの変更を信頼できるソースへ反映する

ここで扱うツールは、数秒でインストールでき、単一コマンドで実行でき、GitフックやCIにも組み込めます。チーム全体のワークフローを確認したい場合は、まず APIコラボレーションツール のまとめを参照してください。

OpenAPI仕様は、各ツールが読み書きする共通フォーマットです。仕様そのものは OpenAPI Specification で定義されています。

APIコラボレーションにおけるCLIツールの「軽量性」とは

CLIツールを選ぶときは、次の条件を満たすかを確認します。

  • インストールが小さい

    単一バイナリ、npx、または npm install -g で導入できる。

  • 起動が速い

    実行して終了するため、スクリプト、Gitフック、CIジョブから呼び出しやすい。

  • 設定が少ない

    openapi.yaml を指定してすぐに使える。常駐サービスや複雑な初期設定を必要としない。

  • ターミナルファースト

    出力を人が読めるだけでなく、CIログ、PRコメント、他コマンドにも渡せる。

  • 用途が明確

    差分、公開、レビュー、マージなど、特定の仕事を確実に実行できる。

以下では、最小構成のGit運用から、差分検証、ドキュメント公開、統合型CLIまで順に紹介します。

Git + 仕様ファイル：まずはこれをベースラインにする

最も軽量な方法は、OpenAPIファイルをコードと同じGitリポジトリで管理することです。openapi.yaml をコミットすれば、Gitだけで履歴、差分、プルリクエスト、レビュー、マージを扱えます。

# 仕様ファイルをコードと同様に追跡する
git add openapi.yaml
git commit -m "GET /orders にページネーションパラメータを追加"

# main ブランチとの差分を確認する
git diff main -- openapi.yaml
Enter fullscreen mode Exit fullscreen mode

実装手順

  1. リポジトリに openapi.yaml または openapi.json を配置する
  2. API変更ごとに仕様ファイルも更新する
  3. プルリクエストで仕様の差分をレビューする
  4. マージ済みブランチを共有仕様の正とする

これは GitネイティブAPIコラボレーション の基本です。

最適な用途： 新しいツールを追加せずに、履歴管理とレビューを始めたい場合。

限界： YAMLの行差分はノイズになりがちです。インデント変更やキー順の変更でも差分が発生します。次に紹介するツールは、テキストではなくAPIの意味を比較するために使います。

oasdiff：破壊的変更をCIで止める

oasdiff は、2つのOpenAPI仕様を比較し、破壊的変更を検出するGo製CLIです。終了コードを返すため、CIのマージゲートにそのまま組み込めます。

# macOS でインストール
brew install oasdiff

# 破壊的変更があれば終了コード 1 を返す
oasdiff breaking main-spec.yaml pr-spec.yaml
Enter fullscreen mode Exit fullscreen mode
  • 終了コード 0：破壊的変更なし
  • 終了コード 1：破壊的変更を検出

変更内容を人が確認する場合は、変更ログを出力します。

oasdiff changelog main-spec.yaml pr-spec.yaml
Enter fullscreen mode Exit fullscreen mode

CIでの使いどころ

PRブランチの仕様と、main の仕様を比較します。

oasdiff breaking openapi-main.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

このコマンドが失敗したら、レビューで対応方法を決めます。たとえば、必須パラメータの追加、レスポンスフィールドの削除、エンドポイントの削除などは、既存クライアントに影響する可能性があります。

最適な用途： 破壊的変更をマージ前に検出するCIゲート。

限界： ドキュメント公開やブランチ管理は行いません。差分比較とレポートに特化したツールです。

Optic：PR向けの構造化されたAPI変更レビュー

Optic は、OpenAPI仕様の差分、リンティング、レビューをGitワークフローに組み込むためのnpmベースCLIです。$ref、oneOf、allOf などを含むスキーマ構造も扱えます。

# インストール
npm install -g @useoptic/optic

# 現在の仕様を main ブランチと比較する
optic diff openapi.yaml --base main --check
Enter fullscreen mode Exit fullscreen mode

oasdiff が「破壊的変更があるか」を判定する用途に向くのに対し、OpticはPRで変更内容をレビューしやすくする用途に向いています。

実装手順

  1. PRブランチで openapi.yaml を更新する
  2. optic diff でベースブランチとの差分を確認する
  3. 禁止したい変更や破壊的変更のルールを設定する
  4. CIで --check を実行する

最適な用途： PR内でAPIレベルの変更を構造化してレビューしたい場合。

限界： Node.js環境が必要です。単一バイナリのツールより導入はやや重く、ルール設定を活用するにはチームで運用方針を決める必要があります。

Bump.sh CLI：仕様を共有ドキュメントとして公開する

Bump.sh CLI は、OpenAPI仕様の公開と差分比較をターミナルから実行できます。仕様が更新されるたびにドキュメントをデプロイすれば、チームやAPIコンシューマーは常に同じリファレンスを参照できます。

# インストール
npm install -g bump-cli

# 共有ドキュメントの新しいバージョンを公開する
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN

# 公開済みの仕様とローカル仕様の差分を確認する
bump diff openapi.yaml --doc my-api
Enter fullscreen mode Exit fullscreen mode

diff の結果は、PRコメントやリリースノートに含める用途にも使えます。

最適な用途： 共有ドキュメントを仕様と同期し、レビュー用の差分も出力したい場合。

限界： ホスト型ドキュメントとデプロイフローは Bump.sh のプラットフォームを利用します。CLIはそのクライアントです。

Redocly CLI：リンティング、バンドル、レジストリ共有

Redocly CLI は、OpenAPI仕様のリンティング、バンドル、共有レジストリへのプッシュを行うツールキットです。

マルチファイル構成の仕様では、$ref を解決して単一ファイルにまとめる bundle が特に役立ちます。レビュー、配布、公開用の成果物を一貫して作れます。

# インストール不要。npx で実行する
npx @redocly/cli lint openapi.yaml

# $ref を解決して単一ファイルへ出力する
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml

# 共有レジストリにプッシュする（APIキーが必要）
npx @redocly/cli push openapi.yaml --organization "Acme" --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

実装パターン 

# CIで実行する例
npx @redocly/cli lint openapi.yaml
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

まず lint でチームのスタイルルールに従っているか確認し、次に bundle で配布用ファイルを生成します。

最適な用途： 仕様のスタイルを統一し、単一のアーティファクトとして共有・公開したい場合。

限界： lint と bundle はローカルで利用できますが、push とレジストリはRedoclyのホスト型機能です。より深い編集フローについては、共同API仕様編集 のガイドも参照してください。

GitHub CLI（gh）：PR作成・レビュー・マージをシェルで進める

レビューがGitHubプルリクエストで行われるなら、GitHub CLI を使うとブラウザを開かずにPR操作を実行できます。

# 仕様変更用のPRを作成する
gh pr create \
  --title "/orders にページネーションを追加" \
  --body "page と limit パラメータを追加"

# レビューを承認する
gh pr review --approve
Enter fullscreen mode Exit fullscreen mode

oasdiffと組み合わせる例

  1. GitHub Actionsで oasdiff breaking を実行する
  2. 破壊的変更があればチェックを失敗させる
  3. gh pr create でPRを作成する
  4. チームメイトが差分とCI結果をレビューする
  5. 承認後にマージする

最適な用途： GitHubを使っているチームが、PRレビューとマージ操作をシェルから行いたい場合。

限界： GitHub CLIはPRを管理するツールであり、APIの意味を理解して破壊的変更を検出するものではありません。oasdiffやOpticと組み合わせて使います。

Apidog CLI：ブランチ、レビュー、マージを統合する

Apidog CLI は、単一目的の差分ツールとは異なり、Apidogプロジェクトの設計、バージョン管理、コラボレーション機能をターミナルから扱うCLIです。

コラボレーションで主に使うコマンドグループは次の3つです。

  • branch
  • merge-request
  • git-connection

Apidogはオープンソースではありませんが、無料ティアがあります。仕様ブランチ、レビュー、マージ、Gitバックアップを1つのワークフローにまとめたい場合に使えます。

1. CLIをインストールして認証する 

npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN
Enter fullscreen mode Exit fullscreen mode

2. 変更用ブランチを作成する

--type でブランチモデルを選択します。

  • sprint：機能追加やリリースなど、スコープのある変更
  • general：継続的な作業
  • ai：エージェントがソースを直接変更せずにリソースを編集する独立ブランチ 
# orders のページネーション追加用ブランチを作成する
apidog branch create --type sprint --name "orders-pagination"
Enter fullscreen mode Exit fullscreen mode

3. マージリクエストを作成する

直接マージせず、マージリクエストをレビューゲートとして使います。保護されたメインブランチに対しても、編集者が変更を提案し、管理者が承認してから反映できます。

# 指定したエンドポイントをレビュー対象として提案する
apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2
Enter fullscreen mode Exit fullscreen mode

4. Gitリポジトリへバックアップする

git-connection を使うと、各モジュールのOpenAPIファイルをGitリポジトリへミラーリングできます。GitHub、GitLab、Azure DevOpsがサポートされています。

# Git連携の利用可能なオプションを確認する
apidog git-connection --help
Enter fullscreen mode Exit fullscreen mode

CLIの出力には agentHints.nextSteps を含む構造化JSONがあり、スクリプトやAIエージェントから操作しやすい設計です。詳細は Apidog CLI完全ガイド を参照してください。

最適な用途： バージョン管理、レビュー、マージを複数ツールに分けず、統合されたCLIワークフローで扱いたい場合。

限界： ローカルのOpenAPIファイルだけを扱う単体ツールではなく、Apidogプロジェクトと連携するプラットフォームCLIです。OpenAPIリンティングにはRedoclyやSpectralを併用してください。ロールベースのアクセス制御も必要なら、RBACによるセキュアなAPIコラボレーション を確認してください。

選び方

ツールは「チームが今必要としているコラボレーション作業」で選びます。

ツール 最適な用途 インストール オープンソース？ 備考
Git + 仕様ファイル 履歴管理とレビュー すでにインストール済み はい（Git） YAML差分はノイズになりやすいため、セマンティック差分ツールと併用する
oasdiff 破壊的変更のマージゲート brew install oasdiff はい（Apache 2.0） 終了コードでCIを失敗させられる
Optic PRでの構造化された変更レビュー npm i -g @useoptic/optic はい（MIT） $ref、oneOf、allOf などを理解する
Bump.sh CLI 共有ドキュメントの公開と差分比較 npm i -g bump-cli CLIはオープン、ホスティングは有料 Node 20+。diff と preview はトークン不要
Redocly CLI リンティング、バンドル、レジストリ共有 npx @redocly/cli CLIはオープン、レジストリは有料 push にはAPIキーが必要
GitHub CLI シェルからのPRレビューとマージ brew install gh はい（MIT） PRを管理する。APIセマンティクスの検証は別ツールで行う
Apidog CLI 統合されたバージョン管理、レビュー、マージ npm i -g apidog-cli いいえ（無料ティアあり） branch、merge-request、git-connection を提供

多くのチームでは、複数ツールを組み合わせる構成が実用的です。

Gitで仕様を管理
  → oasdiff または Optic でPRを検証
  → Bump.sh または Redocly でドキュメントを公開
  → GitHub CLIでレビューとマージを操作
Enter fullscreen mode Exit fullscreen mode

ブランチ、レビュー、マージを単一CLIで運用したい場合は、Apidog CLIを選択できます。スタック全体の比較は、APIコラボレーションチームツール ガイドを参照してください。

まとめ

ターミナルベースのAPIコラボレーションは、次の3ステップに整理できます。

  1. 仕様をバージョン管理する：Git
  2. 変更をレビューする：oasdiff、Optic
  3. 共有変更をマージ・公開する：GitHub CLI、Bump.sh、Redocly、Apidog CLI

まずは openapi.yaml をGit管理に入れ、PRで oasdiff breaking を実行するところから始めるのが最小構成です。共有ドキュメントが必要になればBump.shまたはRedoclyを追加し、統合されたブランチ・レビュー・マージフローが必要なら Apidog CLI を検討してください。

複数ツールをつなぎ合わせずに始めるなら、Apidogをダウンロード して apidog-cli をインストールし、最初のブランチとマージリクエストを作成します。


bash
npm install -g apidog-cli
apidog branch create --type sprint --name "my-api-change"
Enter fullscreen mode Exit fullscreen mode

Top comments (1)

Collapse
 
topstar_ai profile image
Luis Cruz •

この記事で紹介された軽量CLIツールは、APIコラボレーションを効率化するための有用な手段となり得ます。特に、oasdiffやOpticのようなツールは、破壊的変更を検出するための強力な機能を提供し、CIにおけるマージゲートの構築に役立ちます。ただし、ツールの選択と導入には、チームのニーズと既存のワークフローを考慮する必要があります。私はこのようなツールを利用して、APIのレビューと公開のプロセスを改善しようと思っています。CIとの統合や、チームでの運用方法について、どのようなベストプラクティスがあると思いますか。