StoplightからApidogへの移行方法（Spec-Firstワークフロー）

Stoplight StudioまたはStoplight PlatformからApidogへの移行を検討されている場合、最初に知っておくべきことは、OpenAPI仕様を再アップロードする必要がないということです。ApidogのSpec-Firstモード（現在ベータ版）は、既存のGitHubまたはGitLabリポジトリに直接接続するため、Gitが真実の源となり、コミット履歴もそのまま保持されます。このガイドでは、Stoplightの設定をエクスポートし、そのディレクトリ規則をApidogの要件に合わせてマッピングし、.stoplight.jsonとtoc.jsonをApidog相当のものに置き換えるまでのすべての手順を説明します。

世界経済フォーラムのようなチームは、すでにGitでOpenAPI仕様をStoplightと並行してドキュメント管理しています。もしあなたのセットアップがこれに当てはまるなら、このガイドはあなたのために書かれたものです。まだ移行を決定する段階ではなく、他の選択肢を検討している場合は、Stoplight Studioの代替案トップの記事で、より広範な選択肢を網羅しています。

ボタン

移行時に変更されないもの

OpenAPIファイル、Gitリポジトリ、そしてブランチ戦略は変更されません。これが重要な前提です。Stoplightは仕様をYAMLまたはJSONファイルとしてソース管理にチェックインします。ApidogはSpec-Firstモードでリポジトリを接続すると、これらの同じファイルを読み取ります。

変更されるのは、その上に重ねられたすべてのものです。つまり、ドキュメントレンダラー、モックサーバー、テストランナー、APIクライアントです。Stoplight Platformがドキュメントを提供し、Postmanがテストを別のツールとして処理する代わりに、Apidogはこれらすべてを1つのワークスペースに統合し、エンジニアが既にコミットしているのと同じOpenAPIファイルと同期させます。

実質的な結果として、移行はデータの移行ではなく、主に設定の入れ替えとなります。

ステップ1: Stoplightプロジェクトアセットをエクスポートする

Apidogを触る前に、Stoplightが保持していて、まだGitにないものすべてをキャプチャしてください。

GitバックエンドでStoplight Studioを使用している場合:

OpenAPI仕様、JSONスキーマモデル、Markdownドキュメントはすでにコミットされています。git pullを実行して、ローカルクローンが最新であることを確認してください。StoplightはOpenAPI Specification形式に従っており、これらの仕様ファイルは変換なしでApidogで動作します。リポジトリの構造は次のようになっているはずです。

your-api-repo/
  .stoplight.json          # プロジェクト設定 (置き換えが必要)
  reference/
    petstore.yaml          # あなたのOpenAPI仕様
  models/
    error.json             # 共有JSONスキーマモデル
  docs/
    introduction.md        # Markdownガイドページ
    authentication.md
  toc.json                 # 目次順序 (置き換えが必要)
  assets/
    images/
      architecture.png

Stoplight Platform（クラウドホスト型、Gitバックエンドなし）を使用している場合:

Stoplight UIから仕様をエクスポートします。各APIプロジェクトを開き、「エクスポート」に進み、OpenAPI YAMLをダウンロードします。Markdownドキュメントの場合、それらを新しいGitリポジトリのdocs/フォルダにコピーします。StoplightはGit以外のプロジェクトの一括エクスポートを提供していないため、APIプロジェクトごとにこの作業を行ってください。

ファイルがGitリポジトリ（GitHubまたはGitLab）にあることを確認したら、次のステップに進みます。

ステップ2: 置き換える設定ファイルを理解する

2つのStoplight固有のファイルがプロジェクト構造を決定します。どちらもApidogに直接の対応物はありませんが、それらが何をするかを理解することで、代わりにApidogで何を構成すべきかが正確にわかります。

Stoplightファイル	機能	Apidogの対応物
`.stoplight.json`	プロジェクトのルート、仕様パス、ドキュメントパス、プロジェクトに含まれるファイルを宣言します	Apidogプロジェクト内のリポジトリ接続設定（ファイルではなくUI経由で設定）
`toc.json`	Stoplightドキュメントサイドバーでのページの順序とグループ化を制御します	Apidogはディレクトリ構造を読み取ります。サイドバーの順序はフラットファイルではなくApidogドキュメントエディタで設定されます
`reference/` 規則	StoplightがOpenAPI仕様ファイルを期待する場所	Apidog Spec-Firstモードで設定可能。デフォルトはリポジトリのルートですが、`reference/`を指すようにできます
`models/` 規則	共有コンポーネント用のJSON Schemaファイル	OpenAPI仕様の`components/schemas`セクションからこれらを参照します。Apidogは`$ref`パスを解決します
`docs/` 規則	Markdownガイドページ	Apidogにドキュメントページとしてインポートします。ディレクトリ階層はサイドバーセクションにマッピングされます

重要な洞察は、.stoplight.jsonとtoc.jsonはStoplight独自のものです。それらをリポジトリに残しておくことはできますが（Apidogは未知のファイルを無視します）、Apidogでは何も制御しません。同等の設定はApidogプロジェクトのUIを通じて行います。

ステップ3: リポジトリをApidog Spec-Firstモードに接続する

Apidog Spec-Firstモードは、GitHubまたはGitLabリポジトリをApidogプロジェクトにリンクする方法であり、OpenAPI仕様は常にGitから読み込まれ、Apidogの内部データベースからは読み込まれません。これにより、Gitが権威ある情報源として維持され、エンジニアは今日と同じようにPRを送信して仕様を更新し続けることができます。

以下が接続フローです。OAuthの許可付与について不明な点がある場合は、GitHubのリポジトリへのサードパーティアプリ接続に関するドキュメントも参照してください。

Apidogで新しいプロジェクトSpec-Firstモードを作成します。
ApidogをGitHubまたはGitLabアカウントで認証し、リポジトリを選択します。

3.ブランチを設定します。本番環境の仕様にはデフォルトブランチ（mainまたはmaster）を、移行テスト中はフィーチャーブランチを使用します。

保存します。Apidogは仕様を読み込み、そこからインタラクティブなドキュメント、モックサーバーのエンドポイント、テストスキャフォールディングを構築します。

仕様が$refを使用してmodels/ディレクトリからスキーマをプルしている場合、Apidogは仕様ファイルの場所を基準としてこれらの参照を解決します。OpenAPIファイルのパスが正しい限り、追加の設定は必要ありません。このGit同期の仕組みをさらに詳しく知りたい場合は、GitHubへのOpenAPI仕様同期ガイドでそのメカニズムが詳細に説明されています。

ステップ4: Markdownドキュメントを移行する

Stoplightでは、MarkdownガイドページとAPIリファレンスドキュメントを1つのサイドバーに混在させることができます。Apidogもそのドキュメントエディタを通じて同様の機能を提供します。

リポジトリを接続した後、docs/Markdownファイルをインポートします。

ApidogプロジェクトでDocsセクションを開きます。
インポート > Markdownを使用し、ファイルをアップロードするか、ページごとにコンテンツを貼り付けます。

Markdownで参照されている画像アセット（通常のStoplightレイアウトではassets/images/フォルダ）については、それらをApidogのファイルストレージにアップロードし、各ページの![alt](path)参照を更新してください。画像がすでにCDNまたは公開URLでホストされている場合は、何も変更する必要はありません。

ステップ5: Stoplightのモックサーバーを置き換える

Stoplight Studioには、OpenAPI仕様を読み込み、サンプル応答を返すローカルモックサーバーが含まれています。Apidogのモックサーバーも同様の機能を提供しますが、クラウドホスト型であり、ローカルプロセスを実行することなくチーム全体でアクセスできます。

仕様がSpec-Firstモードで接続されると、ApidogはOpenAPIファイルで定義されたすべての操作に対してモックエンドポイントを自動生成します。サンプル応答は仕様のexamplesフィールドから取得されるか、例が定義されていない場合はApidogのスマートモックエンジンから生成されます。仕様ファイルに手を加えることなく、Apidog内でエンドポイントごとに応答ルールを上書きできます。

ローカルでstoplight mock reference/your-api.yamlを実行することに慣れているチームにとっての変更点は、QAエンジニアとフロントエンド開発者が共有のクラウドURLにアクセスするようになることです。これは、ネットワークアクセスポリシーに適合しているかを確認するために、トライアルで検証する価値があります。

ステップ6: テストスイートを再構築する

Stoplightの契約テストまたはSpectralルールをリンティングに使用していた場合、これらは別途処理する必要があります。

Spectralリントルール: Stoplightは、.spectral.yamlファイルを通じて設定されるOpenAPIリンティングにSpectralを使用します。ApidogにはOpenAPI準拠のための独自の組み込みリントルールがありますが、Spectralを直接実行するわけではありません。チームが依存しているカスタムSpectralルールがある場合、Apidogとは独立してCI（GitHub ActionsまたはGitLab CI）でそれらを実行し続けてください。Apidogのリンティング範囲と、プロジェクト間でカスタムリントルールセットを共有できるかどうかは、特定のルール要件に対してトライアルで検証する価値があります。

APIテスト: Stoplight PlatformにはシナリオベースのAPIテストが含まれています。Apidogのテストランナーを使用すると、テストシナリオを視覚的に構築し、リクエストを連結し、応答ボディ、ヘッダー、ステータスコードに対してアサーションを実行できます。これらはApidog内で再構築する必要があります。Stoplightテストプロジェクトからの自動インポートはありません。GitネイティブAPIワークフローガイドでは、Apidogテスト実行をGitHub Actionsパイプラインに統合する方法を示しています。

具体的な例を挙げます。もしStoplightテストでPOST /ordersがlocationヘッダー付きで201を返すことを検証していた場合、Apidog CLIを使用したCIパイプラインでの同等のApidogテスト設定は次のようになります。

# .github/workflows/api-tests.yml
name: API契約テスト

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Apidogテストを実行
        run: |
          npx apidog-cli run \
            --project-id ${{ secrets.APIDOG_PROJECT_ID }} \
            --test-id ${{ secrets.APIDOG_TEST_SUITE_ID }} \
            --env production \
            --reporter junit \
            --output test-results.xml
        env:
          APIDOG_API_KEY: ${{ secrets.APIDOG_API_KEY }}

      - name: テスト結果を公開
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: test-results.xml

これはCIでのStoplightテスト実行を置き換え、既存のGitHub Actions構造をそのまま維持します。

エンタープライズチームのための評価チェックリスト

より大規模なチーム（StudioではなくStoplight Platformを評価するようなチーム）のために移行する場合、コミットする前に検証すべき特定の機能があります。Apidogはこれらの領域をカバーしていますが、正確な動作はプランとワークスペースの設定によって異なります。

機能	Apidogトライアルで検証すべきこと
プライベートドキュメントアクセス	認証済みユーザーまたは特定のメールアドレスドメインにドキュメントページを制限できますか？アクセス制御要件と照合して確認してください。
プロジェクト間でのスキーマ/コンポーネントの再利用	共有の`components/schemas`ライブラリを、コピー＆ペーストせずに複数のApidogプロジェクトから参照できますか？実際のスキーマファイルでテストする価値があります。
カスタムリントルールの共有	共有のリンティングプロファイル（共有`.spectral.yaml`に相当）を、同じワークスペース内の複数のApidogプロジェクトに配布できますか？
SSO/SCIMプロビジョニング	ApidogのSSOはあなたのIDプロバイダーをサポートしていますか？SCIMプロビジョニングの粒度がユーザーライフサイクル管理プロセスに適合しているか確認してください。
監査ログ	監査ログはどのようなイベントをどのような形式でキャプチャしますか？コンプライアンスまたはセキュリティレビュー要件を満たしているか確認してください。

これらをブロッキング要因ではなく、評価タスクとして捉えてください。ほとんどは、代表的なプロジェクトを使った2週間のトライアルで確認できます。

よくある質問

ApidogとSpectralを併用できますか？

はい、可能です。SpectralはApidogとは独立してCIパイプラインで実行してください。.spectral.yamlファイルはリポジトリに残り、CIジョブ（GitHub Actions、GitLab CI）はすべてのPRでOpenAPIファイルをリンティングします。Apidogはドキュメント、モック、テストを扱い、Spectralはリンティングを扱います。これらは競合しません。CI統合オプションについては、Spectralのドキュメントを参照してください。

リポジトリをApidogに接続すると、`$ref`パスが壊れますか？

仕様ファイル内のパスが正しければ、壊れません。ApidogはルートOpenAPIファイルの場所を基準として$refを解決します。もし仕様が$ref: '../models/error.json'と記述されており、models/フォルダがreference/より1階層上にある場合、Apidogはリポジトリ内のその相対パスに従います。まず外部参照を使用する仕様でテストしてください。

Apidog Spec-FirstモードはGitHubだけでなくGitLabもサポートしていますか？

はい、GitHubとGitLabの両方がサポートされています。接続フローは同じです。GitLabアカウントで認証し、リポジトリとブランチを選択します。バージョン管理オプションの詳細については、GitによるOpenAPIバージョン管理ガイドでブランチ戦略が詳細に説明されています。

移行後、既存のStoplightドキュメントURLはどうなりますか？

StoplightがホストするドキュメントURL（docs.stoplight.io/your-org/your-api）は、Stoplightのサブスクリプションをキャンセルすると機能しなくなります。Apidogは、設定したサブドメイン上に新しいドキュメントURLを提供します。Stoplightのドキュメントページを指す外部リンクがある場合は、DNSまたはCDNレイヤーでリダイレクトを設定してください。

リポジトリから`.stoplight.json`と`toc.json`を削除する必要がありますか？

いいえ。Apidogは認識しないファイルを無視します。削除するとマージの競合や混乱を招く可能性がある場合は、そのままにしておいてください。チーム全体がApidogに完全に移行した後、クリーンアップPRで削除することもできますが、移行を機能させるために必須ではありません。

結論

StoplightからApidogへの移行は、最初からやり直すことを意味しません。あなたのOpenAPI仕様はGitに残り、ブランチワークフローはそのまま維持され、reference/、models/、docs/のディレクトリ構造はApidogが期待するものにきれいにマッピングされます。移行は設定の交換です。つまり、.stoplight.jsonとtoc.jsonをApidogのプロジェクト設定に置き換え、Spec-Firstモードでリポジトリを接続し、Apidogのテストランナー内でテストシナリオを再構築します。

既存のGitHubまたはGitLabのOpenAPIリポジトリにApidog Spec-Firstモードを接続することからStoplightからの移行を開始してください。再アップロード、ロックインなし、Git履歴もそのままです。Apidogをダウンロードして開始し、トライアルでは代表的なAPIプロジェクトを使用して、上記の評価チェックリストを実際のデータで確認してください。

ボタン