API設計向け無料オープンソースCLIツール

APIデザインは、コードがデプロイされるはるか前に仕様ファイルで行われます。忘れがちなスタイルルール、見落としがちな破壊的変更、先週リリースしたものからずれてしまうスキーマなど、これらすべては後になってから修正する方がコストがかかります。コマンドラインは、これらの問題が発生した場所でそれを検出し、誰かがUIをクリックすることなくCI内でそれを行います。

この記事は、そのツールチェーンのオープンソース側に焦点を当てています。ここにあるすべてのツールは、寛容なライセンスの下でソースが利用可能であり、シートコストなしで自由に実行でき、自己ホストまたは自分で管理するバージョンに固定できます。これは、APIデザインがGitリポジトリに存在し、すべてのラップトップとすべてのパイプラインで同じ方法でチェックを実行したい場合に重要です。APIの設計方法に関する私たちのガイドから始めて、これらのツールがどのように連携するかをより広く理解し、その後でここに立ち戻ってCLIを選択してください。

ここでは6つのツールを紹介します。それぞれに実際のインストールコマンドと動作を確認できるコマンドが含まれています。スタイルルール用のリンター、その高速なGoベースの代替品、検証機能も備えたバンドラー、コードとドキュメントジェネレーター、そして仕様バージョン間の破壊的変更を検出するための2つのツールです。OpenAPI Specificationは、これらすべてが共通で話す言語であるため、あるツールでリントした仕様は次のツールにきれいに渡されます。

まず正直な注意点です。ここではApidogが紹介されていますが、これはオープンソースではありません。無料プランのある商用製品であり、仕様をリントするものではありません。そのため、オープンソースの項目ではなく、正確な補足情報として記載されています。以下のツールが真のオープンソースデザインツールチェーンです。

APIデザインにおけるCLIツールがオープンソースである条件

オープンソースは「雰囲気」ではなく、具体的な主張です。このリストでは、以下の3つの条件が満たされた場合にツールが認定されます。

第一に、ライセンスです。実際に読み取り可能な寛容なライセンス、またはコピーレフトライセンスである必要があります。ここではMITとApache-2.0が最も多く見られます。これにより、ライセンス料やシート数なしで商用プロジェクトでツールを使用できます。

第二に、自己ホスティングとバージョン管理です。バイナリをベンダー提供し、厳密なバージョンを固定し、エアギャップされたCIランナーで完全にオフラインで実行できます。ここにあるツールは、その主要なジョブを実行するためにホームに電話をかけたり、アカウントを必要としたりすることはありません。

第三に、メンテナンスとコミュニティです。最近のコミットがあり、回答が得られるオープンな問題があり、公開された変更ログがあるリポジトリです。放棄されたプロジェクトはMITライセンスであっても、悪い選択である可能性があるため、重要な場合はメンテナンス状況を明記します。

以下のすべてのツールは、これらの3つの条件に対してチェックされています。プロジェクトが現状維持に甘んじている場合は、その旨を指摘します。

Spectral: 柔軟なOpenAPIスタイルリンター

StoplightのSpectralは、API記述のためのリファレンスとなるオープンソースリンターで、Apache-2.0ライセンスです。これはルールセット（ルールをリストアップしたYAML、JSON、またはJavaScriptファイル）を読み込み、OpenAPI 3.x、OpenAPI 2.0、AsyncAPI、およびArazzoドキュメントに適用します。チームにAPIスタイルガイドが書かれている場合、Spectralはそれを実行可能にする方法です。

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

標準では、記述の欠落、無効な例、構造上の問題を指摘するoasルールセットが含まれています。真の価値はカスタムルールにあります。すべての操作にoperationIdを必須とする、エラー応答に共有スキーマを使用する、パスに命名規則を設けるなどです。これらのルールはリポジトリに存在し、すべての貢献者に対して同じように実行されます。

得意なこと: チームのスタイルガイドをコードとして強制すること。正直な限界: Spectralは単一の仕様をチェックします。2つのバージョンを比較しないため、破壊的変更を検出するには差分ツールと組み合わせて使用する必要があります。

vacuum: 最速のリンター、Spectralルールセットの代替として利用可能

Spectralが標準であるなら、vacuumは速度重視の選択肢です。これはGo製のリンターで、MITライセンスであり、Spectralルールセットと100%互換性があります。そのため、すでに作成したルールセットと同じものを指定でき、大規模な仕様に対してはるかに高速な結果を得られます。これはプレコミットフックや厳密なCIループでまさに求められるものです。

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml

-dフラグはルールごとの詳細な出力を提供します。vacuumはリント以上のことも行います。同じ仕様からHTMLレポートやドキュメントを生成します。Nodeランタイムがない単一のコンパイル済みバイナリであるため、高速に起動し、コンテナにきれいに組み込めます。

得意なこと: 既存のルールセットを使用して大規模な仕様を高速にリントすること。正直な限界: ルールセットのエコシステムとドキュメントはまだSpectralが中心であるため、多くの場合、Spectralのモデルに対してルールを作成し、それをvacuumで実行することになります。これは機能ですが、最初に学ぶべきはやはりSpectralであることを意味します。

Redocly CLI: リントとバンドルを1つのバイナリで

Redocly CLIはMITライセンスで、少し異なる役割を担っています。リントも行いますが、その際立った機能はbundleです。これは、多くの$refファイルに分割された仕様（大規模なAPIデザインを保守可能に保つための健全な方法）を、単一ファイルを期待するツールのために1つのドキュメントに平坦化します。また、バンドルされた結果からAPIリファレンスドキュメントも生成します。

npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml

仕様をリソースごとのファイルに分割することで、差分が読みやすくなり、マージの競合が小さく抑えられます。これはGitネイティブなAPIデザインワークフローの核となる部分です。Redoclyのbundleは、その複数ファイルのソースを、CI、モックサーバー、またはドキュメントサイトが利用する単一の成果物に戻すステップです。

得意なこと: バンドルと検証が必要な複数ファイル仕様プロジェクト。正直な限界: そのデフォルトのリントルールは、完全なカスタムSpectralルールセットよりも軽量であるため、多くのチームはバンドルのためにRedoclyを、詳細なスタイル強制のためにSpectralまたはvacuumを使用しています。

openapi-generator: デザインからクライアント、スタブ、ドキュメントを生成

デザインは、他の人がそれに基づいて構築できるようになるまで完成しません。openapi-generatorはApache-2.0ライセンスで、OpenAPI仕様から数十の言語でクライアントSDK、サーバスタブ、ドキュメントを生成します。仕様を唯一の真理の源とし、残りを生成するというアプローチは、私たちがAPIデザイン原則で説明しているスキーマファースト、契約駆動型アプローチの中核です。

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

-g typescript-axiosをgo、python、java、kotlin、またはサポートされている多くのジェネレーターのいずれかに置き換えてください。仕様が変更されるたびにCIで実行すれば、クライアントライブラリが契約からずれることはありません。

得意なこと: 生成されたコードとドキュメントをデザインと同期させること。正直な限界: 実行にはJDK（JDK 11以降）が必要であり、生成されたコードは多くの場合カスタマイズが必要な出発点であり、ジェネレーターの品質はターゲット言語によって異なります。出荷する前に出力を確認してください。

oasdiff: 破壊的変更がクライアントに到達する前に検出

リンターは1つの仕様がクリーンであるかどうかを教えてくれますが、フィールドの名前変更が本番環境のすべてのクライアントを壊したかどうかは教えてくれません。oasdiffは、そのギャップを埋めるApache-2.0 Goツールです。これに仕様の2つのバージョンを与えると、差分、特に破壊的変更を報告します。

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml

breakingコマンドは、既存のコンシューマーを壊す変更のみを浮上させます。changelogは、破壊的かどうかに関わらず、すべての変更の人間が読めるリストを提供します。diffは、機械が読める完全な差分を提供します。oasdiff breakingをプルリクエストのチェックに組み込めば、破壊的変更は午前3時の呼び出しではなく、ビルド失敗になります。

得意なこと: CIで破壊的変更をゲートすること。正直な限界: 仕様を比較するため、実際のAPIと仕様を最新の状態に保つ規律にかかっています。スタイルをリントするものではありません。Spectralまたはvacuumと併用してください。

Optic: メンテナンス上の注意点付きで差分とリントを一緒に

OpticはMITライセンスで、他のツールが分割していることを1つで行います。1つのツールでOpenAPIをリントおよび差分比較し、2つのバージョンを比較して破壊的変更を指摘しながらスタイルルールも適用します。観測されたテストトラフィックから仕様を生成することさえ可能です。

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

オープンソースリストとして正直にお伝えします。Opticの公開リポジトリは2026年初頭にアーカイブされ、プロジェクトはもはや活発にメンテナンスされていません。MITライセンスのソースはまだ動作するため、ベンダー化することはできますが、新しいルールやセキュリティパッチは得られません。今日の破壊的変更検出には、oasdiffがメンテナンスされている選択肢です。Opticがリストに残っているのは、既存のパイプラインでまだ出会う可能性があるためです。

得意なこと: すでに投資しているチーム、または1つのCLIでリントと差分を行いたい人。正直な限界: 2026年初頭現在、もはやメンテナンスされていません。レガシーとして扱い、移行パスを計画してください。

Apidogが適合する場所（としない場所）

Apidogはオープンソースではなく、OpenAPIのリントやスタイルルールの強制は行いません。Spectral、vacuum、Redoclyがリンターです、それだけです。Apidogが提供するのは異なるトレードオフです。6つの異なるバイナリを組み合わせる代わりに、無料プランとapidog-cliバイナリにより、エンドポイントとデータスキーマを設計する統合された場所を提供し、その結果をOpenAPIとしてエクスポートして、これらのオープンソースチェックに直接フィードバックできます。

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml

CLIにはendpoint、schema、mock、import/exportのコマンドグループがあり、ターミナルからAPIデザインをスクリプト化し、エクスポートされた仕様をopenapi-generatorやoasdiffに渡すことができます。完全なApidog CLIガイドで、全コマンドセットを確認してください。正直な説明として、Apidogはオープンソースツールチェーンとうまく連携する商用かつ統合されたオプションであり、リンターの代替品ではなく、オープンソースプロジェクト自体でもありません。

選び方

ツールを仕事に合わせましょう。ほとんどのチームは、これらのツールのうち2つか3つを組み合わせて使用しており、1つだけではありません。

実用的なスタックは、スタイルにはSpectralまたはvacuum、バンドルにはRedocly、破壊的変更にはoasdiff、クライアント生成にはopenapi-generatorです。これほど多くのツールを管理するのが大変な場合は、統合プラットフォームが設計とエクスポートの部分をまとめてカバーします。CLI以外のツール環境をより広く知りたい場合は、API設計とテストのためのSwagger代替ツールに関するガイドと、REST APIの設計方法の基本をご覧ください。

まとめ

APIデザインのためのオープンソースCLIツールチェーンは成熟しており、無料で実行できます。Spectralとvacuumはリントを行い、Redoclyはバンドルし、openapi-generatorはクライアントを生成し、oasdiffは破壊的変更から保護します。Opticはレガシーオプションとして認識されます。これらをCIに組み込めば、プッシュごとにAPI契約がチェックされ、シートごとのコストやベンダーロックインは発生しません。

もし、エンドポイントとスキーマを1つの統合ツールで設計し、クリーンなOpenAPIを同じパイプラインにエクスポートしたい場合は、Apidogをダウンロードしてapidog-cliをお試しください。これはオープンソーススタックの商用コンパニオンであり、リンターの代替品ではありません。どちらの方法でも、目標は同じです。ユーザーに届く前に、ターミナルでデザインの問題を発見することです。