DEV Community

Cover image for StoplightからApidogへの移行ガイド：Spec-FirstモードでのOpenAPI仕様管理
Akira
Akira

Posted on • Originally published at apidog.com

StoplightからApidogへの移行ガイド：Spec-FirstモードでのOpenAPI仕様管理

StoplightからApidogへの移行は、OpenAPIファイルを1つインポートする作業ではありません。OpenAPI仕様、Markdownドキュメント、JSONスキーマ、画像、toc.json、.stoplight.json、さらにテストやモックを含む、ファイルベースのAPIワークフロー全体を移行する作業です。

今すぐApidogを試す

Stoplightプロジェクトには、エンドポイント定義以外にも次のような資産が含まれていることがあります。

  • Gitで管理するOpenAPI仕様
  • Markdownドキュメント
  • JSONスキーマモデル
  • ローカル画像
  • toc.json によるドキュメントナビゲーション
  • .stoplight.json のパス設定
  • PostmanまたはBrunoのリクエスト例
  • CIで実行するテストやバリデーション

OpenAPIだけを移行すると、エンドポイント一覧は残せても、ドキュメント構造、テスト、モック、共同作業フローが分断される可能性があります。

Apidog Spec-firstモードでは、OpenAPIファイルを唯一の信頼できる情報源（SSOT）として維持しながら、ドキュメント、モック、テスト、レポート、権限管理、チーム共同作業へ接続できます。

操作手順はSpec-firstモードのヘルプガイドを参照してください。

Stoplight移行がOpenAPIインポート以上である理由

OpenAPIはAPI契約を定義します。一方、Stoplight形式のプロジェクトには、契約を補完するファイル構造とドキュメント資産が含まれます。

代表的な構成は次のとおりです。

project/
├── reference/          # OpenAPI / Swagger ファイル
├── docs/               # Markdown ドキュメント
├── models/             # JSON Schema モデル
├── images/             # ローカル画像
├── .stoplight.json     # パス設定
└── toc.json            # ドキュメントナビゲーション
Enter fullscreen mode Exit fullscreen mode

移行対象をOpenAPIファイルだけに限定すると、次の問題が起こり得ます。

  • MarkdownドキュメントがAPI仕様から切り離される
  • 既存のナビゲーション順序が変わる
  • JSONスキーマモデルの参照関係が不明確になる
  • 画像参照が壊れる
  • Postman、Bruno、CIにあるテストが別管理のまま残る
  • Git上の仕様と新しいAPIワークスペースが乖離する

そのため、移行は単一ファイルではなく、リポジトリ全体のファイルツリーを監査するところから開始します。

移行モデル：引き継ぎ、レビュー、再構築、接続

Stoplightからの移行では、すべてをそのまま複製しようとしないことが重要です。Stoplight固有の設定や表示挙動には、別のワークスペースへ1対1で対応しないものがあります。

以下の4カテゴリに分けて計画してください。

カテゴリ 対象 移行方針
引き継ぎ OpenAPI、Markdown、JSONスキーマ、ローカル画像、対応する.stoplight.json設定、対応するtoc.json入力 ファイルベースのプロジェクトコンテキストとして取り込む
レビュー リンク、アンカー、画像、$ref、TOC、命名、レンダリング差分、Stoplight ID 本番利用前に検証する
再構築 Postman/Brunoフロー、環境、手動テスト、モック、CI、公開ルール OpenAPIを中心に新しいワークフローとして組み直す
接続 ドキュメント、モック、テスト、CIレポート、権限、共同作業 APIライフサイクル全体へ接続する

StoplightからApidogへの移行モデル

移行には2つのレイヤーがあります。

  1. ファイルレイヤー

    OpenAPI、Markdown、スキーマ、画像、プロジェクト構成ファイルを扱います。

  2. ワークフローレイヤー

    変更レビュー、ドキュメント公開、モック、テスト、CI、権限、チーム共同作業を扱います。

Spec-firstモードは特にファイルレイヤーと相性がよく、Apidogはその契約をワークフローレイヤーへ接続する役割を担います。

Apidog Spec-firstモードをStoplightプロジェクトに適用する

Apidog Spec-firstモードは、ファイルベースのAPI運用を前提にしています。

  • Git接続プロジェクト

    Gitリポジトリとブランチを信頼できる情報源として維持し、Apidogと同期します。

  • ファイルバックアッププロジェクト

    まずApidog上で仕様ファイルを管理し、必要になったタイミングでGitを接続します。

  • 仕様ワークスペース

    ソースファイル、解析済みAPI構造、編集フローを1か所で確認します。

Spec-firstモードでOpenAPIファイルを管理するためのApidog仕様ワークスペース

仕様ワークスペースでは、チームがソースファイル、解析されたAPI構造、および編集ワークフローを1か所で管理できます。

Stoplightアセットごとの扱い

Stoplightアセット Apidogでの扱い レビュー項目
OpenAPI / Swagger APIモジュール、エンドポイント、スキーマ、例として取り込み・同期可能 $ref、変換警告、モジュール名、グループ化
.stoplight.json 対応するパス設定、OpenAPIインクルード、除外、tocPathの検出に利用 すべてのStoplight設定が再現される前提にしない
toc.json DOCSフォルダ、Markdown順序、タイトル、OASリンク、モデル参照の構成に利用 最終サイドバーの構造を確認
Markdown プロジェクトドキュメントとして取り込み可能 相対リンク、アンカー、書式、レンダリング
ローカル画像 Markdownから参照される画像を対象に取り込み可能 壊れた参照、外部URL、データURI、未使用画像
JSON Schema 対応するプロジェクト構造から明示的に参照されるモデルを取り込み可能 名前、フォルダ、形式、参照
Stoplight ID 同期時のモジュール照合に利用される場合がある リソース単位で完全に保持されるとは限らない

.stoplight.json と toc.json の注意点

.stoplight.json は、主に同期対象を見つけるためのパス設定として扱います。対応範囲には、次のような項目が含まれます。

  • OpenAPI、Markdown、JSONスキーマのルートディレクトリ
  • OpenAPIのインクルードパターン
  • グローバル除外パターン
  • tocPath

ただし、すべてのStoplight formats 設定やプロジェクト固有の挙動がそのまま適用されるとは限りません。

toc.json は、次のようなドキュメント構造の再作成に役立ちます。

  • DOCSフォルダ
  • Markdownのフィルタリングと順序付け
  • グループ・区切り・タイトル
  • OASモジュールへのリンク
  • 選択した仕様項目へのリンク
  • TOCから参照するJSONスキーマモデルの取り込み

ただし、最終的なオンラインドキュメントはApidogのDOCS/OAS/MODELSモデルでレンダリングされます。Stoplightのナビゲーションや任意のクロスタイプ順序を完全に再現できるとは限りません。

ファイルインポートから接続されたAPIワークフローへ

従来のインポートでは、OpenAPIを一度取り込んだ後に新しいツール上で編集を続けるため、Git上の仕様とAPIワークスペースが乖離しがちです。

Spec-firstモードでは、ファイルを基盤として維持します。

Git接続型プロジェクトでは、仕様ワークスペースでファイルを編集し、変更をコミットしてリポジトリへプッシュできます。ファイルバックアップ型では、Git接続前にApidog上で仕様を編集・保存できます。

責任範囲を明確に分けると、移行後の運用が安定します。

責任 推奨する情報源
API契約 OpenAPI / Swaggerファイル
プロジェクト構造 Gitリポジトリまたはファイルバックアップツリー
Stoplight形式の対応パス設定 .stoplight.json
ドキュメントナビゲーション入力 toc.json とMarkdown
日常的なAPI共同作業 Apidogプロジェクトワークスペース
モック、テスト、レポート、権限 Apidogプラットフォームのワークフロー

ポイントは、ファイルを移動するだけで終わらせず、OpenAPI契約を中心に利用可能なAPIワークスペースを構築することです。

Git接続型とファイルバックアップ型の選び方

Stoplightユーザーの移行元は、必ずしも同じ成熟度のGit運用ではありません。

パス 向いているチーム 一般的な流れ
Git接続型Spec-firstプロジェクト GitでOpenAPIを管理し、PRレビューを行っているチーム リポジトリ接続 → ブランチ同期 → 編集 → コミット → プッシュ
ファイルバックアップ型Spec-firstプロジェクト Git接続前に仕様管理や編集体験を検証したいチーム ファイル操作 → 変更保存 → ワークフロー検証 → 必要に応じてGit接続

長期的には、GitリポジトリをAPI契約の信頼できる情報源として維持できるGit接続型が明確です。

一方で、ファイルバックアップ型は次の用途に向いています。

  • 移行前にオーサリング体験を検証したい
  • 既存のプロジェクト構造を整理したい
  • Gitワークフローの導入を段階的に進めたい

移行後のレビュー項目

インポートが成功しても、そのまま本番運用へ移行するのは避けてください。特に大規模なドキュメントサイト、外部参照が多い仕様、複雑なTOCを持つプロジェクトでは、明示的なレビューが必要です。

項目 確認内容
OpenAPIモジュール 必要な仕様がすべて取り込まれ、モジュール名とエンドポイントグループが正しいか
外部参照 $ref が期待どおりに解決されているか
Lint / バリデーション OpenAPIの仕様検証を実行し、検出された問題を確認したか
.stoplight.json ルート、インクルード、除外、tocPath が期待どおり反映されているか
toc.json グループ、順序、タイトル、リンク、最終サイドバーを確認したか
Markdown 見出し、相対リンク、アンカー、API操作へのリンクを確認したか
画像 ローカル画像が表示されるか、外部画像・データURI・未使用画像を確認したか
JSON Schema モデル名、フォルダ、形式、参照関係が正しいか
Stoplight ID 繰り返し同期した場合にもモジュール照合が期待どおりか
テストとモック Postman、Bruno、CIなどで管理していたシナリオを再接続したか
権限と公開 チームアクセス、可視性、レビュー、リリース責任を設定したか

Spectralベースのバリデーション

移行後は、インポートされたOpenAPIファイルに対して仕様バリデーションを実行してください。

Apidogは、次のルートレベル設定を利用できます。

.spectral.yaml
.spectral.yml
.spectral.json
.spectral.mjs
Enter fullscreen mode Exit fullscreen mode

また、Spectralベースのエディタバリデーションでは .stoplight/styleguide.json にフォールバックできる場合があります。

ただし、バリデーションの成功は、Stoplight固有のスタイルガイド運用や表示挙動が完全に移行されたことを意味しません。検出結果はレビューの起点として使用してください。

PostmanとBrunoのアセットは別途計画する

PostmanコレクションやBrunoの.bruファイルは、OpenAPI仕様とは異なる移行対象です。

  • OpenAPI: API契約を定義する
  • Postman / Bruno: リクエストフロー、例、環境、テストを定義することが多い

移行前に、以下を確認してください。

質問 重要な理由
OpenAPIとコレクションのどちらが信頼できる情報源か？ Spec-first移行は権威ある契約から始める必要がある
維持すべきリクエスト例は何か？ 必要な例を新しいAPIワークスペースに再構築するため
継続すべきテストは何か？ テストをドキュメント移行の副産物として扱わないため
共有人環境やシークレットは何か？ 仕様移行とは別に環境管理を設計するため
既存CIは何に依存しているか？ バリデーション、テスト、レポートを意図的に再接続するため

Brunoを利用している場合、Gitネイティブな運用はすでに価値があります。Spec-firstモードはOpenAPI契約をファイルベースで維持できますが、Bruno資産自体は、利用方法に応じて個別に移行・再構築・置き換えを検討してください。

推奨する移行計画

すべてのAPIワークフローを一度に移すのではなく、段階的に進めます。

段階的な移行計画：まずOpenAPI契約を移動し、その後、周囲のワークフローを再接続します。

1. Stoplight形式のリポジトリを監査する

以下を洗い出します。

  • OpenAPIファイル
  • .stoplight.json
  • toc.json
  • Markdownドキュメント
  • JSONスキーマモデル
  • ローカル画像
  • Postman / Brunoコレクション
  • CI設定、テストスクリプト

たとえば、リポジトリ内の関連ファイルは次のように確認できます。

find . \
  \( -name "*.yaml" -o -name "*.yml" -o -name "*.json" -o -name "*.md" -o -name "*.bru" \) \
  | sort
Enter fullscreen mode Exit fullscreen mode

2. 信頼できる情報源を決める

Git内のOpenAPIが契約の信頼できる情報源かを確認します。

コレクション側にしか存在しないリクエスト例、パラメータ、テスト条件がある場合は、移行前にOpenAPIと実運用の差分を整理してください。

3. Spec-firstプロジェクトを作成する

  • Gitを信頼できる情報源として継続するなら、Git接続型を選びます。
  • まずファイルワークフローを検証するなら、ファイルバックアップ型を選びます。

4. 引き継がれた資産をレビューする

最低限、以下を確認します。

  • APIモジュール
  • エンドポイントグループ
  • Markdownドキュメント
  • JSONスキーマモデル
  • ローカル画像
  • 内部リンクとアンカー
  • toc.json のナビゲーション入力
  • .stoplight.json の対応パス設定
  • OpenAPIバリデーション結果

可能な限り、表示上の症状を手作業で修正するのではなく、Git上のプロジェクトファイルを修正して同期してください。

5. ワークフローレベルの資産を再構築する

移行済みのAPI契約を中心に、以下を再接続します。

  • モック
  • テストシナリオ
  • リクエスト例
  • CIジョブ
  • レポート
  • 権限
  • 公開責任
  • チーム通知やレビュー運用

6. 最初の実変更を新しいフローで実行する

小さなOpenAPI変更を1つ選び、次の流れを実際に通します。

仕様変更
  ↓
レビュー
  ↓
同期・コミット
  ↓
ドキュメント更新
  ↓
モック確認
  ↓
テスト実行
  ↓
CIレポート確認
Enter fullscreen mode Exit fullscreen mode

この1サイクルを通すことで、移行後のワークフローに不足がないか確認できます。

この移行パスが向いているケース

次の条件に当てはまるチームには、この移行パスが適しています。

  • OpenAPIまたはSwagger仕様をファイルとして管理している
  • StoplightプロジェクトにMarkdown、モデル、画像、.stoplight.json、toc.jsonが含まれる
  • APIレビューがGitブランチやプルリクエストに依存している
  • ドキュメント、モック、テスト、レポートをAPI契約へ接続したい
  • フロントエンド、QA、プロダクト、プラットフォーム、パートナーとの乖離を減らしたい

一方、次の場合は追加の計画が必要です。

  • 実際の信頼できる情報源がOpenAPIではなくPostmanやBrunoコレクションである
  • Stoplight固有の公開挙動に大きく依存している
  • 外部リンク、アンカー、生成ページ、未参照アセットが大量にある
  • JSONスキーマが手動レビューを要する形式や構造になっている
  • Stoplightのナビゲーションとレンダリングをピクセル単位で再現したい

よくある質問

Apidog Spec-firstモードはStoplightの代替になりますか？

OpenAPIプロジェクトをファイルベースで維持しながら、ドキュメント、モック、テスト、レポート、権限、共同作業を追加したいチームにとって、代替の選択肢として利用できます。

OpenAPI仕様をGitに保持できますか？

はい。Git接続型Spec-firstプロジェクトでは、Gitを信頼できる情報源として維持し、ブランチ同期、ファイル編集、コミット、プッシュを行えます。

開始するためにGitは必要ですか？

いいえ。最初はファイルバックアップ型Spec-firstプロジェクトで仕様を操作し、後からGitを接続できます。

.stoplight.json と toc.json は完全に保持されますか？

いいえ。Apidogは対応する部分を移行入力として使用します。

.stoplight.json は主にパス検出に使用され、対応するOpenAPI、Markdown、JSONスキーマのルート、OpenAPIインクルード、グローバル除外、tocPathが対象です。

toc.json はDOCSコンテンツ、OAS/モジュールリンク、選択した仕様項目リンク、TOC参照モデルの構成に利用できます。ただし、最終サイドバーはApidogのDOCS/OAS/MODELSモデルに依存するため、Stoplightの表示順を完全に再現できない場合があります。

Markdownドキュメントはどうなりますか？

MarkdownドキュメントはSpec-firstプロジェクトに取り込めます。toc.json に含まれるドキュメントは、対応範囲で構造を保持できます。移行後に内部リンク、アンカー、画像、レンダリングを確認してください。

JSONスキーマモデルはどうなりますか？

toc.json などの対応するプロジェクト構造で明示的に参照されたJSONスキーマは、対応範囲でモデルとして取り込めます。モデルディレクトリ内のすべてのJSONが自動的にモデル化されるとは限らないため、名前、フォルダ、形式、参照を確認してください。

画像はどうなりますか？

Markdownから参照されるローカル画像は、対応範囲で取り込めます。formats.image.rootDir を、そのディレクトリ内の全画像がインポートされる保証として扱わないでください。外部画像、データURI、壊れた参照、未使用画像は別途レビューが必要です。

移行後にLintやバリデーションを実行すべきですか？

はい。インポート後にOpenAPI仕様のバリデーションを実行してください。Spectral設定や.stoplight/styleguide.jsonを利用できる場合がありますが、成功したとしてもStoplight固有のすべての挙動が保持されていることを意味するわけではありません。

BrunoまたはPostmanのユーザーはどうすべきですか？

まず、OpenAPIとコレクションのどちらが信頼できる情報源かを明確にしてください。Spec-first移行はOpenAPIと関連プロジェクトファイルを中心に実施します。コレクションベースのリクエスト、環境、テストは個別に移行または再構築する必要があります。

Apidogはモック、テスト、CI/CD、レポート、共同作業もサポートしますか？

はい。Spec-firstモードはファイルベースのAPI契約をApidogへ接続し、より広範なApidogプラットフォームでは、契約を中心としたドキュメント、モック、テストシナリオ、Apidog CLIによるCI/CD実行、レポート、権限、チーム共同作業を利用できます。

まとめ

Stoplightからの移行は、ファイルベースのAPI開発を捨てることではありません。

Gitリポジトリを信頼できる情報源として維持しながら、OpenAPI、Markdown、参照画像、TOC参照JSONスキーマ、対応するプロジェクト構造をポータブルかつレビュー可能な状態で扱えます。

実装の順序は明確です。

  1. リポジトリ構造を監査する
  2. API契約の信頼できる情報源を決める
  3. Spec-firstプロジェクトを作成する
  4. 引き継いだファイルと構造をレビューする
  5. モック、テスト、CI、権限、公開フローを再接続する
  6. 小さな変更を1つ通して運用を検証する

Apidog Spec-firstモードを使うと、Stoplight形式のファイルベース資産を活かしながら、APIドキュメント、モック、テスト、レポート、権限、共同作業を1つのAPIライフサイクルへ接続できます。

エンタープライズ移行計画については、Apidog Enterpriseを参照してください。

Top comments (0)