npm install -g @apidevtools/swagger-cli を実行した後に警告に気づいてここにたどり着いた方へ：手短に言うと、このツールはもはやメンテナンスされていません。GitHubのswagger-cliリポジトリには、「膨大なユーザーベースの期待に応えようとするメンテナンスの負担が、ほとんど貢献がないにもかかわらず大きい」という理由で、廃止されたと明記されています。README自体が、後継としてRedocly CLIを指し示しています。
したがって、代替品が必要です。これは、具体的にvalidateとbundleを行うswagger-cliターミナルツールに関するものです。もし、Swagger Editor、SwaggerHub、またはより広範な設計スイートのことを指しているのであれば、代わりにAPIテストもできる7つのSwagger代替ツールを読んでください。
swagger-cliが何を行っていたかを見てから、現在使用すべきツールの正直な候補リストを見ていきましょう。
swagger-cliが実際に行っていたこと
正確に把握しておくことが重要です。なぜなら、適切な代替品はあなたが何を使用していたかによって異なるからです。
swagger-cliには、正確に2つのコマンドがありました。
# Validate a Swagger 2.0 / OpenAPI 3.0 definition against the schema and check $refs
swagger-cli validate openapi.yaml
# Follow $ref pointers and combine a multi-file definition into one file
swagger-cli bundle openapi.yaml -o bundled.json
bundleコマンドには、少数のオプションがありました。ファイルに書き込むための-o/--outfile、JSONまたはYAMLを選択するための-t/--type、すべての$refを完全にインライン化するための-r/--dereference、およびインデントのための-f/--formatです。
それがこのツールのすべてです。構造を検証し、複数ファイルのスペックをバンドルしました。スタイルルールでリントしたり、ドキュメントを生成したり、テストを実行したり、何かをモックしたりすることはありませんでした。swagger-cliがスペックを「リント」したという主張を読んだとしたら、それは間違いです。OpenAPIスキーマに対して定義をチェックし、参照を解決するだけでした。この範囲を覚えておいてください。なぜなら、いくつかの代替ツールははるかに多くのことを行い、それを望む場合と望まない場合があるからです。
候補リスト
swagger-cliを使っていたほとんどすべての理由をカバーする3つのツールと、特筆すべき専門ツールがいくつかあります。正直な説明は以下の通りです。
Redocly CLI：公式の後継であり、最も近い1対1の代替
Redocly CLI（@redocly/cli、バイナリはredocly）はオープンソースであり、swagger-cliのREADME自体が推奨するツールです。Redoclyはswagger-cliからの移行ガイドも公開しています。もしあなたの目標がドロップインのターミナルバリデーターおよびバンドラーであるなら、ここから始めてください。
swagger-cliをインストールしたのと同じ方法でインストールします。
npm install -g @redocly/cli@latest
# or run without installing
npx @redocly/cli@latest lint openapi.yaml
マッピングは明確です。swagger-cliのvalidateはredocly lintとなり、スペックをチェックし、設定可能なスタイルルールを適用します。swagger-cliのbundleはredocly bundleとなります。
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
以下に、バンドルフラグのマッピングを並べて示します。
| swagger-cli | Redocly CLI | 目的 |
|---|---|---|
-o, --outfile |
--output (または -o) |
ファイルに書き込む |
-t, --type |
--ext (json, yaml, yml) |
出力フォーマット |
-r, --dereference |
-d, --dereferenced |
すべての$refを完全にインライン化する |
知っておくべきことの一つは、redocly lintはデフォルトでswagger-cliのvalidateよりも多くのことを行う点です。スキーマチェックだけでなく、スタイルガイドのルールセットも適用します。もしswagger-cliが提供していたような単純な構造的検証が必要な場合は、specルールのみを含むredocly.yamlを設定し、redocly lint openapi.yamlを実行してください。このルールセットの挙動は、Redoclyの欠点ではなく、その特徴的な強みです。ターミナルネイティブなガバナンスを求めるチームが好む理由もここにあります。ルールセット（minimal、recommended、recommended-strict、spec）を調整したり、カスタムルールを作成したりできます。他のリンターとどのように連携するかについては、最高のOpenAPIリンターセットアップを参照してください。
Redocly CLIは、swagger-cliの2つのコマンドを超えた機能も提供します。単一の記述を複数ファイルの構造にsplit（バンドルの逆）したり、複数のファイルをjoin（実験的）したり、スタンドアロンのRedoc HTMLドキュメントを構築したりできます。
redocly build-docs openapi.yaml -o docs.html
できないこと：APIテストの実行やモックサーバーのホスト。これはコードファーストでターミナルネイティブなリント/バンドル/ドキュメントツールであり、非常に優れたものです。これだけが必要なら、読み進めるのをやめて今日中に移行できます。
Apidog：検証とバンドル以上のものを求める場合
正直な言い方をすれば、swagger-cliは検証とバンドルを行うための静的なスクリプトでした。しかし、ほとんどのチームにとって、検証とバンドルは目的のための手段です。スペックが正しいことを確認するために検証し、移植性を確保するためにバンドルし、その後モックを作成し、テストし、ドキュメント化します。swagger-cliは、これらの後のステップを他のツールに任せていました。
Apidogはそのギャップを埋めます。これはオールインワンのAPIプラットフォームで、設計、モック、テスト、ドキュメントを1つのワークスペースで行え、インポート、エクスポート、CIテスト実行を処理するCLIを備えています。swagger-cliがファイルを提供したのに対し、Apidogはそのファイルから構築された生きたワークスペースを提供します。
swagger-cliの操作を最も直接的にマッピングする2つのコマンドは、importとexportです。まずCLIをインストールし、認証してください。
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
トークンはApidogアプリまたはウェブから取得します：アバター、次にアカウント設定、次にAPIアクセストークン。これは~/.apidog/config.tomlに保存されるため、決して出力したりコミットしたりしないでください。
インポートがあなたの検証ステップです。 これは定義をプロジェクトに取り込み、複数ファイルの$refを統合されたリソースに解決します。ファイルが不正な形式の場合、インポート時にそれを検出します。
apidog import --project 123456 --format openapi --file ./openapi.json
インポートはOpenAPI以外にも、Postman、HAR、Insomnia、WSDL、JSON Schemaなど、様々な形式をサポートしており、ソースが混在している場合に便利です。
エクスポートはあなたのバンドルステップであり、おまけ付きです。 これは単一の統合されたファイルを出力し、出力時にOpenAPIのバージョンを選択できます。これにより、バンドルとオプションのスペックアップグレードを1つのコマンドで行うことができます。
# Bundle and upgrade to OpenAPI 3.1 in one shot
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Or emit standalone HTML docs
apidog export --project 123456 --format html --output ./docs.html
CIの場合、Apidogはswagger-cliにはなかったステップ、すなわちテスト実行を追加します。
# Run a test scenario in CI with multiple report formats
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
# Or run fully offline from an exported collection file
apidog run ./collection.apidog-cli.json
CLIはまた、endpoint、schema、mock、environment、branch、test-suite、test-reportなどのプロジェクトリソースを直接管理します。設定の詳細とすべてのフラグについては、Apidog CLI完全ガイドおよび公式Apidog CLIドキュメントを参照してください。
次に、誇大広告よりも適合性が重要であるため、正直な制限について説明します。ApidogのCLIはインポート時に構造を検証しますが、Redoclyのlintのように、カスタムルールセットを持つ設定可能なコードファーストのスタイルガイドリンターを提供するわけではありません。apidog lintコマンドはなく、CLIを介してSpectralスタイルのカスタムルールを作成することはできません。また、splitやjoinもありません。ApidogはGUIファーストです。設計、モック、ビジュアルテスト構築、ドキュメント作成は主にデスクトップアプリまたはウェブアプリで行われ、CLIはプロジェクトに対するインポート、エクスポート、CIテスト実行、リソース管理を処理します。そしてApidogはフリーミアムであり、オープンソースではないため、Redocly CLIやSpectralとは異なるモデルです。
Spectral：CIにおける純粋でカスタマイズ可能なリンティング
もしswagger-cliに本当に求めていたのが、パイプラインでの厳格で意見のある検証だったなら、専用のリンターはStoplightのSpectralです。これはオープンソースであり、OpenAPI（およびその他のJSON/YAML）ドキュメントにカスタマイズ可能なルールセットを適用するという1つの仕事のために構築されています。
Spectralは、プルリクエストごとに独自のルールでハウススタイルをコードとして強制したい場合に真価を発揮します。バンドルせず、ドキュメントを生成せず、エンドポイントをテストしません。リントするだけです。これをバンドラーと組み合わせると、swagger-cliが実行していたことの焦点を絞ったバージョンを再構築でき、さらに真のガバナンスも実現します。Spectral OpenAPIリンティングのガイドではルールセットの記述方法を解説し、CIでのOpenAPI検証ではパイプラインへの組み込み方をカバーしています。
手短に：openapi-generatorとvacuum
さらに2つのツールについて触れておきましょう。正確で短い説明です。openapi-generatorはコードおよびクライアントジェネレーターです。バンドルする理由がジェネレーターへの入力だった場合、スペックを直接消費するため、個別のバンドルステップはまったく必要ないかもしれません。vacuumはGoで書かれた高速なSpectral互換のOpenAPIリンターで、大規模なモノリポでリント速度が重要な場合に良い選択肢です。どちらも単独では一般的な検証＋バンドルの代替品ではありませんが、特定のニーズには適合します。
比較表
swagger-cliユーザーが関心を持つ傾向にある機能に関して、各オプションがどのように比較されるかを示します。
| ツール | 検証 | バンドル | リントルール | ドキュメント | モック | テスト | オープンソース | 最適 |
|---|---|---|---|---|---|---|---|---|
| swagger-cli | はい | はい | いいえ | いいえ | いいえ | いいえ | はい（廃止） | 新しいものはなし；メンテナンスされていません |
| Redocly CLI | はい（lint） |
はい | はい（設定可能） | はい（Redoc HTML） | いいえ | いいえ | はい | ガバナンスを備えたドロップインのターミナル検証/バンドル交換 |
| Apidog | はい（インポート時） | はい（エクスポート時、OASアップグレード付き） | 構造のみ、カスタムルールセットなし | はい（アプリ + エクスポート） | はい | はい（CLI実行） | いいえ（フリーミアム） | APIライフサイクル全体のワンツール |
| Spectral | はい（リントベース） | いいえ | はい（カスタムルールセット） | いいえ | いいえ | いいえ | はい | CIにおける厳格でカスタマイズ可能なリンティング |
| vacuum | はい（リントベース） | いいえ | はい（Spectral互換） | いいえ | いいえ | いいえ | はい | 大規模スペックでの高速リンティング |
推奨
これは「すべてが素晴らしい、お気に入りを選べ」という状況ではありません。ほとんどすべての人をカバーする2つの明確な道筋があります。
ドロップインの代替を求めるならRedocly CLIを選んでください。 これは公式の後継であり、オープンソースであり、移行はほとんど機械的です：validateをlintに、bundleをbundleに（上記のフラグマッピングを使用）。もしあなたのワークフローが本当に「ターミナルから検証とバンドルを行う」だけで、後からツールを変えることなくガバナンスルールを追加したいのであれば、Redoclyは明白な選択肢です。swagger-cliが存在していたのと同じく、コードファーストでターミナルネイティブな状態を維持できます。
検証とバンドルが始まりに過ぎなかった場合はApidogを選んでください。 ほとんどのチームは、それ自体のためにスペックを検証するわけではありません。検証した後、誰かがモックを必要とし、別の誰かがテストを作成し、さらに別の誰かがドキュメントを担当します。swagger-cliは最初のステップで止まり、残りをSpectral、バンドラー、Postman、Newmanから組み立てる必要がありました。Apidogは、インポート（検証）、エクスポート（バンドルとOASバージョンアップグレード）、モック、テスト、ドキュメントを1つのワークスペースに統合し、CIに属する部分にはCLIを提供します。もはやメンテナンスされていない静的なスクリプトを気にすることなく、バンドル後も有用な状態でスペック全体を管理できる場所へと移行できます。
これらは異なるパラダイムであり、同じものの競合バージョンではありません。Redocly CLIは、ターミナルから純粋に実行する軽量な設定駆動型スペシャリストです。Apidogは、たまたま高機能なCLIを持つオールインワンプラットフォームです。1つのツールでライフサイクルのどこまでをカバーしたいかに基づいて選択し、正直になりましょう。もしターミナルでリントとバンドルだけを行いたいのであれば、Redoclyの方が軽量で無料です。
ライフサイクルアプローチを試したい場合は、Apidogをダウンロードして既存のスペックをインポートしてください。無料で開始でき、クレジットカードも不要で、数分でバンドルされバージョン管理された出力を確認できます。
よくある質問
swagger-cliはまだメンテナンスされていますか？
いいえ。swagger-cliのGitHubリポジトリは廃止予定とマークされており、大規模なユーザーベースに対して貢献が少ないことを理由に、もはやメンテナンスされていません。まだインストールして実行できますが、修正や更新は行われないため、移行を計画してください。
swagger-cliの代替は何ですか？
プロジェクト自身のREADMEは、Redocly CLIを後継として指し示しています。redocly lintがswagger-cli validateの代替となり、redocly bundleがswagger-cli bundleの代替となります。Redoclyは専用の移行ガイドも公開しています。検証とバンドル以上のものを求めるなら、Apidogがインポート、エクスポート、モック、テスト、ドキュメントをすべて一箇所でカバーします。
Apidogは無料ですか？
Apidogはフリーミアムです。クレジットカードなしで始められる無料プランがあり、大規模なチームや高度なニーズ向けの有料プランもあります。オープンソースではないため、オープンライセンスが必須要件である場合は、Redocly CLIやSpectralとは主要な違いとなります。
swagger-cliのワークフローを完全にそのまま維持できますか？
最も近いのはRedocly CLIです。swagger-cliの単純な構造的validateを模倣するには、specルールのみを含むredocly.yamlを設定し、redocly lintを実行します。バンドルに関しては、コマンドとフラグがほぼ1対1でマッピングされます。元のツールの範囲を深く掘り下げるには、ターミナルからswagger-cliを使用する方法を参照してください。