DEV Community

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

Posted on • Originally published at apidog.com

API設計におすすめの軽量CLIツール

ほとんどのAPIデザインツールは、必要以上に重くなりがちです。命名規則のチェック、分割された仕様書のバンドル、破壊的なフィールド名変更の検知だけが目的でも、デスクトップアプリの起動やサービスの構築が必要になることがあります。CLIなら、これらの作業の多くをセットアップ不要の1コマンドで実行できます。

今すぐApidogを試す

この記事では、APIデザイン用の軽量CLIツールチェーンを紹介します。ここで扱うツールは、インストールと起動が速く、役割が明確です。多くはアカウント作成を必要とせず、長い設定ファイルを書く前に結果を確認できます。単一バイナリまたはnpxコマンドで実行できるため、ローカル環境とCIの両方へそのまま組み込めます。

設計全体の進め方を確認したい場合は、まずAPIの設計方法を確認してください。本記事では、次の6つを扱います。

  • 仕様リンター
  • バンドラー兼バリデーター
  • コード・ドキュメントジェネレーター
  • 破壊的変更を検出する2つの方法
  • ターミナルからエンドポイントとスキーマを設計するApidog CLI

共通フォーマットにはOpenAPI Specificationを使用します。あるツールの出力を次のツールへ渡せるため、チェック・バンドル・差分検出・コード生成をパイプライン化できます。

API設計でCLIツールを軽量と判断する基準

軽量性は機能数ではなく、フットプリントと導入時の摩擦で決まります。以下の3点を満たすツールを優先すると、開発環境とCIの両方で扱いやすくなります。

  1. インストールが少なく、すぐ起動できること

    単一バイナリ、またはグローバルインストール不要のnpx実行が理想です。クリーンなコンテナでも数分の準備なしに実行できる状態を目指します。

  2. 最初の結果に設定が不要、または最小限であること

    まず仕様ファイルを渡すだけでlintやbundleが動き、ルールの厳格化は後から追加できると導入しやすくなります。

  3. ターミナルファーストでスクリプト化できること

    終了コードが明確で、構造化出力またはgrep可能な出力を持ち、GUI操作を前提にしないことが重要です。これにより、ローカルとプルリクエスト検証で同じコマンドを使えます。

以下では、導入しやすい順にツールを紹介します。

Redocly CLI: ゼロインストールでlintとバンドル

Redocly CLIは、npxで直接実行できるため、最も手軽に導入できます。CI、一時的な検証、他メンバーの環境でのチェックにも向いています。MITライセンスで、主にlintとbundleを担当します。

npx @redocly/cli@latest lint openapi.yaml
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

マルチファイル構成の仕様では、bundleが特に便利です。$refで分割したファイルを、ドキュメントサイト、モックサーバー、後続ツールが利用しやすい単一のOpenAPIファイルへまとめられます。

例えば、次のようにリソース単位で仕様を管理できます。

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── schemas/
    ├── User.yaml
    └── Order.yaml
Enter fullscreen mode Exit fullscreen mode

変更差分を小さく保ち、マージ競合を減らしたうえで、CIではバンドル済みファイルを使う構成です。これはGitネイティブなAPI設計ワークフローと相性がよい方法です。

npx @redocly/cli@latest bundle openapi/openapi.yaml \
  -o dist/openapi.yaml

npx @redocly/cli@latest lint dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

最も適している用途: マルチファイル仕様のバンドルと簡易検証。

注意点: デフォルトルールだけではチーム固有のスタイルを十分に強制できない場合があります。詳細なスタイルルールにはSpectralを併用してください。

Spectral: スタイルガイドをルールとして強制する

StoplightのSpectralは、API記述向けのオープンソースリンターです。Apache-2.0ライセンスで、OpenAPI 3.x、OpenAPI 2.0、AsyncAPI、Arazzoを対象にできます。

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

設定なしで仕様を渡すと、組み込みのoasルールセットによって、説明不足、無効なexample、構造上の問題などを確認できます。

チームのAPIスタイルガイドを適用するには、.spectral.yamlをリポジトリに追加します。例えば、すべての操作にoperationIdを必須にするルールは次のように書けます。

extends:
  - spectral:oas

rules:
  operation-operationId:
    description: すべての操作に operationId を設定する
    given: $.paths[*][get,post,put,patch,delete,options,head]
    then:
      field: operationId
      function: truthy
Enter fullscreen mode Exit fullscreen mode

実行します。

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

このようにルールをコードとして管理すれば、ローカル開発、CI、レビュー時で同じ基準を適用できます。API設計原則を、実行可能なルールセットに落とし込む用途に適しています。

最も適している用途: チームの命名規則やスタイルガイドの強制。

注意点: Spectralは1つの仕様を評価するツールです。バージョン間の互換性比較には、oasdiffなどの差分ツールを使ってください。

oasdiff: 単一バイナリで破壊的変更を検知する

リンターは仕様そのものの品質を確認できますが、フィールド名の変更や必須パラメータの追加が既存クライアントを壊すかどうかまでは判定できません。

oasdiffは、この差分検出を行うCLIです。Apache-2.0ライセンスのGoバイナリで、ランタイムのセットアップなしに利用できます。

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

主なコマンドは次のとおりです。

# 既存コンシューマーを壊す変更を検出する
oasdiff breaking old-openapi.yaml new-openapi.yaml

# 人間が読みやすい変更履歴を出力する
oasdiff changelog old-openapi.yaml new-openapi.yaml

# 完全な差分を機械可読形式で取得する
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

プルリクエストでbreakingを実行すると、互換性を壊す変更をマージ前に検出できます。

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

終了コードをCIの判定に使うことで、破壊的変更をリリース後の障害ではなくビルド失敗として扱えます。

最も適している用途: CIでの破壊的変更のゲート。

注意点: 実装とOpenAPI仕様が同期していることが前提です。スタイルlintは行わないため、SpectralまたはRedoclyと組み合わせてください。

Optic: 1つのCLIでlintとdiffを実行する（注意点あり）

Opticは、OpenAPIのlint、diff、破壊的変更検出を1つのCLIで扱えるMITライセンスのツールです。

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

ただし、導入判断ではメンテナンス状況に注意してください。公開リポジトリは2026年1月にアーカイブされ、プロジェクトは現在メンテナンスされていません。ソースコードは利用できますが、新しいルールやセキュリティパッチは期待できません。

既存パイプラインで利用している場合は動作を維持できる可能性がありますが、新規導入では、メンテナンスされているより軽量な選択肢としてoasdiffを検討してください。

最も適している用途: すでにOpticへ投資しており、lintとdiffを1つのCLIで実行したいチーム。

注意点: 2026年初頭時点でメンテナンスされていません。レガシーとして扱い、移行を計画してください。

openapi-generator: 仕様からクライアント、スタブ、ドキュメントを生成する

API仕様は、他の開発者が実装や統合に利用できる状態になって初めて価値を発揮します。openapi-generatorはApache-2.0ライセンスで、OpenAPI仕様からクライアントSDK、サーバースタブ、ドキュメントを多数の言語向けに生成できます。

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

-gには生成対象を指定します。例えば次のように変更できます。

# Go クライアント
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go

# Python クライアント
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python

# Java クライアント
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
Enter fullscreen mode Exit fullscreen mode

CIで仕様変更ごとにコード生成を実行すれば、SDKとAPIコントラクトの乖離を減らせます。仕様を信頼できる唯一の情報源として扱い、周辺成果物を生成する考え方は、デザインファーストAPI開発の基本です。

最も適している用途: SDK、サーバースタブ、ドキュメントを仕様と同期させること。

注意点: JDK 11以降が必要です。生成コードは出発点であり、用途に応じてカスタマイズが必要になる場合があります。また、ジェネレーターの品質は言語ごとに異なります。

Apidog CLI: ターミナルからエンドポイントとスキーマを設計する

ここまでのツールは、すでに存在するOpenAPI仕様を検証・変換するものです。Apidogは、その前段階であるエンドポイントとデータスキーマの設計を扱います。

軽量に利用するには、apidog-cliをインストールします。

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog schema list
apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

CLIでは、次のコマンドグループを利用できます。

  • endpoint: エンドポイントの管理
  • schema: データモデルの管理
  • security-scheme: 認証方式の管理
  • folder: APIの整理
  • mock: モック関連の操作
  • import / export: 仕様の入出力

ターミナルから設計作業をスクリプト化し、結果をOpenAPIとしてエクスポートできます。エクスポート後は、Spectral、Redocly、oasdiff、openapi-generatorへそのまま渡せます。

# OpenAPI をエクスポート
apidog export --format openapi -o openapi.yaml

# スタイルを検証
spectral lint openapi.yaml

# クライアントを生成
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

コマンドの出力は構造化されたJSONで、agentHints.nextStepsも含まれます。後続処理へ接続しやすい設計です。コマンド一覧はApidog CLI完全ガイドを参照してください。

ApidogはOpenAPIのlintやスタイルルール強制を行うツールではありません。これらはSpectralやRedoclyの役割です。また、Apidogはオープンソースではなく、無料ティアのある商用製品です。エンドポイントとスキーマを設計し、クリーンなOpenAPIをエクスポートする統合された入口として利用できます。

最も適している用途: 1か所でAPI仕様を設計し、OpenAPIとしてエクスポートすること。

注意点: リンターではなく、オープンソースでもありません。上記CLIを置き換えるのではなく、補完する位置付けです。

選び方

多くのチームでは、1つだけを選ぶのではなく、2〜3個を組み合わせます。

ツール 最も適している用途 インストール方法 オープンソース？ 備考
Redocly CLI バンドル + 簡易lint npx @redocly/cli@latest はい（MIT） npx経由でゼロインストール。マルチファイル仕様に適する
Spectral スタイルガイドのlint npm i -g @stoplight/spectral-cli はい（Apache-2.0） ゼロコンフィグで開始でき、カスタムルールも記述可能
oasdiff 破壊的変更の検出 go install github.com/oasdiff/oasdiff@latest はい（Apache-2.0） 単一Goバイナリ。メンテナンスされている
Optic lint + diffを1つで実行 npm i -g @useoptic/optic はい（MIT） 2026年1月にリポジトリがアーカイブ。レガシー扱い
openapi-generator SDK / スタブ / ドキュメント生成 npm i -g @openapitools/openapi-generator-cli はい（Apache-2.0） JDK 11+が必要。ここで紹介した中では最も重い
Apidog CLI エンドポイント設計 + 仕様エクスポート npm i -g apidog-cli いいえ（無料ティアあり） リンターではない。OpenAPIの設計・エクスポートを担当

実用的な軽量スタック

最小構成としては、次の流れが実用的です。

# 1. Apidog CLI で OpenAPI を出力
apidog export --format openapi -o openapi.yaml

# 2. Spectral でスタイルを検証
spectral lint openapi.yaml

# 3. Redocly で分割仕様をバンドルする場合
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# 4. oasdiff で破壊的変更を検出
oasdiff breaking main-openapi.yaml dist/openapi.yaml

# 5. 必要に応じて SDK を生成
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

役割ごとに分けると、次のようになります。

  1. 設計: Apidog CLI
  2. スタイル検証: Spectral
  3. バンドル: Redocly CLI
  4. 互換性検証: oasdiff
  5. SDK・ドキュメント生成: openapi-generator

CLI以外の選択肢も含めて確認したい場合は、API設計とテストのためのSwagger代替、またはREST APIの設計方法も参照してください。

まとめ

軽量なAPI設計CLIツールチェーンは、小さく、速く、CIに組み込みやすい構成です。

  • Redocly CLI: インストール不要でlintとbundle
  • Spectral: APIスタイルガイドの強制
  • oasdiff: 破壊的変更の検出
  • openapi-generator: クライアント、スタブ、ドキュメントの生成
  • Optic: 既存環境向けのレガシー選択肢
  • Apidog CLI: エンドポイントとスキーマの設計、OpenAPIエクスポート

仕様を設計したら、pushやプルリクエストごとにこれらのチェックを実行してください。GUIに依存せず、同じコマンドをローカルとCIで再利用できます。

エンドポイントとスキーマを1か所で設計し、そのままOpenAPIをパイプラインへ渡したい場合は、Apidogをダウンロードしてapidog-cliを試してください。これはオープンソースのlint・差分検出ツールの代替ではなく、その前段にある設計ステップを補完するものです。

Top comments (0)