DEV Community

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

Posted on • Originally published at apidog.com

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

APIデザインの品質は、コードをデプロイする前の仕様ファイルで決まります。命名ルールの漏れ、見落とした破壊的変更、前回リリースからずれたスキーマは、リリース後に直すほどコストが高くなります。CLIツールを使えば、ローカル環境とCIで同じチェックを実行し、UI操作なしで問題を検出できます。

今すぐApidogを試す

この記事では、APIデザイン向けのオープンソースCLIツールチェーンを実装目線で紹介します。取り上げるツールは、寛容なライセンスまたはコピーレフトライセンスでソースが公開されており、シート単位のコストなしで実行できます。自己ホスト、バージョン固定、オフラインCIランナーでの実行にも向いています。

まずはAPIの設計方法を確認して、APIデザイン全体の流れを押さえてください。そのうえで、本記事のCLIを組み合わせると、Gitリポジトリ上のOpenAPI仕様を継続的に検証できます。

ここでは、スタイルルールを検査するリンター、高速なGo製リンター、バンドラー、コード・ドキュメントジェネレーター、仕様間の破壊的変更を検出する差分ツールを紹介します。OpenAPI Specificationはこれらのツールの共通フォーマットです。そのため、あるツールでリントした仕様を、そのまま別のツールの入力として利用できます。

Apidogはオープンソースではありません。本記事では、OpenAPIのリント機能を持つオープンソースCLIとは区別し、設計・エクスポートを補完する商用オプションとして紹介します。

APIデザイン向けCLIを「オープンソース」と呼ぶ条件

このリストでは、次の3条件を満たすツールをオープンソースとして扱います。

  1. ライセンスが明確であること

    MIT、Apache-2.0などの寛容なライセンス、またはコピーレフトライセンスで公開されていること。商用プロジェクトでもライセンス料やシート数を気にせず利用できます。

  2. 自己管理・バージョン固定ができること

    バイナリやコンテナイメージを固定し、外部アカウントなしでCI上に導入できること。エアギャップ環境でも主要な処理を実行できることが重要です。

  3. メンテナンス状況を確認できること

    最近のコミット、公開Issue、変更履歴が確認できること。ライセンスがOSSでも、保守停止したツールは新規採用に向かない場合があります。

Spectral: OpenAPIスタイルガイドをルールとして実行する

StoplightのSpectralは、Apache-2.0ライセンスのAPI記述リンターです。OpenAPI 3.x、OpenAPI 2.0、AsyncAPI、Arazzoを対象に、YAML・JSON・JavaScriptで定義したルールセットを適用できます。

インストールして、まず標準ルールセットで仕様を検査します。

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

チーム固有のルールは .spectral.yaml に置き、リポジトリで管理します。たとえば、すべての操作に operationId を必須にするルールは次のように定義できます。

extends: spectral:oas

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

実行コマンドは同じです。

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Spectralは、説明文の不足、無効なexample、構造上の問題を検出できます。さらに、以下のようなチームルールをコードとして強制できます。

  • すべての操作に operationId を付与する
  • エラーレスポンスで共通スキーマを使う
  • パスやタグの命名規則を統一する
  • 必須のレスポンスコードを定義する

向いている用途: APIスタイルガイドの継続的な強制

注意点: 1つの仕様を検査するツールです。旧仕様と新仕様を比較して破壊的変更を検出するには、oasdiff などを併用します。

vacuum: Spectralルールセットを高速に実行するGo製リンター

Spectral互換のルールセットを、高速に実行したい場合はvacuumが選択肢になります。vacuumはMITライセンスのGo製リンターで、Spectralルールセットと100%互換です。

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

-d を付けると、ルールごとの詳細な結果を確認できます。

vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

vacuumは単一のコンパイル済みバイナリとして実行できるため、Node.jsランタイムを入れたくないCIコンテナや、短い実行時間が求められるプレコミットフックに組み込みやすい構成です。また、同じ仕様からHTMLレポートやドキュメントを生成する機能も備えています。

既存の .spectral.yaml をそのまま使えるため、ルール作成はSpectral中心、実行はvacuum中心という構成にもできます。

向いている用途: 大規模な仕様の高速リント、プレコミットフック、短時間のCIジョブ

注意点: ルールセットの事例やドキュメントはSpectralを中心に提供されることが多いため、ルール設計ではSpectralのモデルを理解しておくとスムーズです。

Redocly CLI: 分割した仕様をリント・バンドルする

Redocly CLIはMITライセンスのCLIで、リント、検証、バンドルを1つのツールで実行できます。特に重要なのは bundle コマンドです。

大規模なOpenAPI仕様は、次のようにリソース単位でファイルを分割することが一般的です。

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

分割構成では差分が読みやすく、マージ競合も小さくできます。これはGitネイティブなAPIデザインワークフローの基本です。

CIやドキュメント生成ツールに渡す前に、$ref を解決した単一ファイルへバンドルします。

npm install -g @redocly/cli

redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

バンドル後の dist/openapi.yaml を、コード生成、モックサーバー、公開ドキュメントの入力として使うと、パイプラインを単純化できます。

向いている用途: 複数ファイルの $ref 構成を使うプロジェクト、バンドルと検証をまとめたい場合

注意点: デフォルトのリントルールは、詳細なカスタムSpectralルールセットより軽量です。スタイル強制はSpectralまたはvacuum、バンドルはRedoclyという役割分担が実用的です。

openapi-generator: 仕様からSDK、サーバースタブ、ドキュメントを生成する

APIデザインは、利用者が実装できる形になって初めて完成します。openapi-generatorはApache-2.0ライセンスで、OpenAPI仕様からクライアントSDK、サーバースタブ、ドキュメントを生成できます。

TypeScript向けAxiosクライアントを生成する例です。

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

仕様を唯一の真理の源として、SDKやスタブを生成する運用は、APIデザイン原則で扱うスキーマファースト・契約駆動開発の実践です。

CIでは、生成後に差分がないことを検査できます。

openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client

git diff --exit-code ./client
Enter fullscreen mode Exit fullscreen mode

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

注意点: 実行にはJDK 11以降が必要です。生成コードは出発点として扱い、利用する言語・ジェネレーターごとに出力を確認してください。

oasdiff: プルリクエストで破壊的変更を止める

リンターは「仕様がルールに従っているか」を検査します。一方、フィールド削除や必須化などが既存クライアントを壊すかどうかは、旧仕様と新仕様を比較しなければ分かりません。

oasdiffは、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

プルリクエストでは、ベースブランチの仕様と現在ブランチの仕様を比較します。

oasdiff breaking \
  main:dist/openapi.yaml \
  dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

oasdiff breaking を必須CIチェックにすれば、破壊的変更は本番障害ではなくビルド失敗として検出できます。

向いている用途: PRでの破壊的変更検出、リリース前の互換性チェック

注意点: 仕様同士を比較するため、実装とOpenAPI仕様を同期させる運用が前提です。スタイル検査にはSpectralまたはvacuumを併用してください。

Optic: リントと差分をまとめて扱う、ただしレガシーとして扱う

OpticはMITライセンスで、OpenAPIのリントと差分比較を1つのCLIで扱えます。2つの仕様バージョンを比較し、破壊的変更を検出しながらスタイルルールを適用できます。また、観測したテストトラフィックから仕様を生成する機能もあります。

npm install -g @useoptic/optic

optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

ただし、採用時にはメンテナンス状況を考慮してください。Opticの公開リポジトリは2026年初頭にアーカイブされており、現在は活発にメンテナンスされていません。MITライセンスのソースをベンダー化して利用することはできますが、新しいルールやセキュリティパッチは期待できません。

新規に破壊的変更検出を導入するなら、メンテナンスされている oasdiff を優先するのが安全です。

向いている用途: すでにOpticに投資している既存チーム、1つのCLIでリントと差分を実行したい場合

注意点: 2026年初頭時点で保守されていません。レガシーツールとして扱い、移行計画を用意してください。

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

Apidogはオープンソースではなく、OpenAPIスタイルルールをリントするツールでもありません。リントにはSpectral、vacuum、Redocly CLIを使います。

一方で、Apidogは、エンドポイントとデータスキーマを設計し、その結果をOpenAPIとしてエクスポートするための統合環境を提供します。エクスポートした仕様は、そのまま本記事のオープンソースツールチェーンへ渡せます。

npm install -g apidog-cli

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

たとえば、Apidogから仕様を出力し、Redoclyでバンドルし、Spectralでリントし、oasdiffで互換性を確認する流れは次のようになります。

apidog export --format openapi -o openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
spectral lint dist/openapi.yaml
oasdiff breaking main:dist/openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

endpoint、schema、mock、import、export の各コマンドについては、完全なApidog CLIガイドを参照してください。

Apidogは、オープンソースのリンターを置き換えるものではありません。設計とエクスポートを補完し、既存のOpenAPIベースCIに接続する商用オプションです。

選び方

ほとんどのチームは1つのツールだけではなく、目的別に2〜3個を組み合わせます。

Tool 最適な用途 インストール オープンソース？ 備考
Spectral スタイルガイドのリント npm i -g @stoplight/spectral-cli はい（Apache-2.0） カスタムルール作成の基準
vacuum 大規模仕様の高速リント brew install --cask daveshanley/vacuum/vacuum はい（MIT） Spectralルールセットを実行可能
Redocly CLI バンドル + 検証 npm i -g @redocly/cli はい（MIT） 複数ファイルの$ref仕様に適する
openapi-generator SDK / スタブ / ドキュメント生成 npm i -g @openapitools/openapi-generator-cli はい（Apache-2.0） JDK 11以降が必要
oasdiff 破壊的変更の検出 go install github.com/oasdiff/oasdiff@latest はい（Apache-2.0） PRチェック向け、メンテナンス中
Optic リント + 差分 npm i -g @useoptic/optic はい（MIT） 2026年初頭にリポジトリがアーカイブ済み
Apidog CLI 統合された設計 + エクスポート npm i -g apidog-cli いいえ（無料プランあり） リンターではない。OpenAPIをエクスポートする

実用的な最小構成は次のとおりです。

  • スタイル検査: Spectral または vacuum
  • 仕様のバンドル: Redocly CLI
  • 破壊的変更検出: oasdiff
  • SDK・スタブ生成: openapi-generator

GitHub ActionsなどのCIでは、次の順番で実行すると扱いやすくなります。

# 1. 分割したOpenAPI仕様を単一ファイルへバンドル
redocly bundle openapi.yaml -o dist/openapi.yaml

# 2. スタイルと構造を検査
spectral lint dist/openapi.yaml

# 3. ベースブランチとの差分から破壊的変更を検出
oasdiff breaking main:dist/openapi.yaml dist/openapi.yaml

# 4. SDKを再生成
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

CLI以外も含めたツール選定を行う場合は、API設計とテストのためのSwagger代替ツールと、REST APIの設計方法も参考になります。

まとめ

APIデザイン向けのオープンソースCLIツールチェーンは成熟しています。

  • Spectralとvacuumでスタイルをリントする
  • Redocly CLIで分割仕様をバンドルする
  • openapi-generatorでSDK・スタブ・ドキュメントを生成する
  • oasdiffで破壊的変更をCI上で止める
  • Opticは既存環境向けのレガシー選択肢として扱う

これらをCIに組み込めば、プッシュごとにAPI契約を検証できます。重要なのは、リリース後に問題を見つけるのではなく、仕様変更を含むプルリクエストの時点で止めることです。

エンドポイントとスキーマを統合環境で設計し、OpenAPIとして同じパイプラインに渡したい場合は、Apidogをダウンロードしてapidog-cliを試してください。Apidogはオープンソースリンターの代替ではありませんが、設計からOpenAPIエクスポートまでを補完できます。

Top comments (0)