Akira

Posted on Jun 5 • Originally published at apidog.com

Stoplight + Postman vs Apidog: API設計、ドキュメント、テストの統合プラットフォーム

OpenAPIの設計・ドキュメントにStoplight、コレクション・テストにPostmanを使っている場合、よく起きる問題は「仕様」と「テスト」が別々に管理されることです。APIコントラクトは1つなのに、Stoplight側のOpenAPI仕様とPostman側のコレクションを個別に更新する必要があります。Apidogは、OpenAPI仕様を設計、ドキュメント、モック、自動テストの単一の信頼できる情報源として扱い、Gitに接続されたワークスペースからAPIライフサイクルをまとめて管理できます。

今すぐApidogを試す

この記事では、StoplightとPostmanを併用する場合の実装上の課題、Apidogに集約する判断ポイント、移行前に検証すべき項目を整理します。仕様ファーストの考え方を確認したい場合は、スペックファーストAPI開発とは？も参考にしてください。

2つのツールを使うと起きる問題

StoplightとPostmanは、それぞれAPIライフサイクルの別領域に強みがあります。

Stoplight: 視覚的なOpenAPIエディタ、Gitベースの仕様管理、自動生成ドキュメント
Postman: コレクション、環境変数、事前リクエストスクリプト、テスト実行、CI実行

組み合わせれば設計からテストまでをカバーできますが、実装現場では次の問題が発生しやすくなります。

1. 仕様とテストが乖離する

OpenAPI仕様はStoplightが管理するGitリポジトリにあり、PostmanコレクションはPostman側にあります。

たとえば、開発者がOpenAPI仕様でリクエストボディのスキーマを変更しても、Postmanのテストは自動更新されません。その結果、QAが古いコレクションを実行し、プロダクトの不具合ではなくツール間の不整合による失敗を調査することになります。

2. 同じ情報を2か所でメンテナンスする

次のような情報は、OpenAPI仕様とPostmanコレクションの両方に現れます。

パスパラメータ
ベースURL
環境別URL
認証方式
リクエスト/レスポンススキーマ

ステージング、本番、EUリージョンなど環境が増えるたびに、StoplightとPostmanの両方を更新する必要があります。

3. 1つのAPIコントラクトに対して請求ラインが2つになる

StoplightのチームプランとPostmanのチームプランを併用すると、1つのAPI契約を管理するために2つの予算項目が発生します。

ツールの役割が明確に分かれている場合は問題ありませんが、仕様、ドキュメント、モック、テストを同じAPIコントラクトから生成したいチームでは、統合プラットフォームのほうが運用コストを下げやすくなります。

Stoplightが得意なこと

Stoplightの強みは、OpenAPI仕様を視覚的に編集できることです。

主な機能は次のとおりです。

YAML/JSONのリアルタイム検証
Spectralによるスタイルガイド適用
非エンジニアにも読みやすいフォームビュー
GitHub/GitLabとの連携
ブランチ保護ルールを使った仕様レビュー
自動生成ドキュメント

Stoplight Docsでは、カスタムドメインでの公開、toc.jsonによる目次制御、内部向けパスの制御、API Explorerの埋め込みなどもできます。

ただし、Stoplightは実行フェーズには強くありません。テストランナー、アサーションエンジン、CIテストレポートは提供されないため、テストはPostmanなど別ツールに移す必要があります。

Postmanが得意なこと

PostmanはAPIリクエストの実行とテストに強いツールです。

代表的な機能は次のとおりです。

コレクションによるリクエスト管理
環境変数
事前リクエストスクリプト
pm.test() によるJavaScriptアサーション
コレクションランナー
Newman CLIによるCI実行
モニターによる定期実行

Postmanのテストは、次のように書けます。

pm.test("Status is 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Response has orderId", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property("orderId");
});

一方で、PostmanコレクションはOpenAPI仕様からインポートされた時点で分岐しやすい構造です。仕様変更を反映するには、再インポートまたは独自の同期スクリプトが必要になります。

プラットフォーム比較：Stoplight vs Postman vs Apidog

機能	Stoplight	Postman	Apidog
ビジュアルOpenAPIエディタ	ネイティブ	部分的	ネイティブ
Spectral / リントルール	ネイティブ	なし	ネイティブ
Gitリポジトリ同期（GitHub, GitLab）	ネイティブ	なし	ネイティブ（スペックファーストモード、ベータ）
ブランチベースのスペックワークフロー	ネイティブ	なし	ネイティブ
自動生成リファレンスドキュメント	ネイティブ	部分的	ネイティブ
インタラクティブドキュメント	ネイティブ	なし	ネイティブ
プライベートドキュメントアクセス制御	ネイティブ	なし	トライアルで検証の価値あり
スペックからのモックサーバー	部分的（Prism）	部分的	ネイティブ
リクエストコレクションランナー	なし	ネイティブ	ネイティブ
JavaScriptテストスクリプト	なし	ネイティブ	ネイティブ
ビジュアルアサーションエディタ	なし	なし	ネイティブ
環境変数管理	なし	ネイティブ	ネイティブ
CI/CD統合（Newman / CLI）	なし	ネイティブ	ネイティブ
スペックからのコントラクトテスト	なし	なし	ネイティブ
プロジェクト間のスキーマ再利用	部分的	なし	トライアルで検証の価値あり
SSO / SCIM	あり（エンタープライズ）	あり（エンタープライズ）	要件と照合して確認
監査ログ	あり	あり	要件と照合して確認

「トライアルで検証の価値あり」とした項目は、組織構造や運用ルールによって評価が変わります。特に、プロジェクト間のスキーマ再利用、レポート権限、監査ログは、実データを使った概念実証で確認してください。

Apidogのスペックファーストモードで変わること

Apidogのスペックファーストモードは、既存のGitHubまたはGitLabリポジトリをOpenAPI仕様の信頼できる情報源として接続します。

一度だけOpenAPIをインポートするのではなく、Git上のコミットとApidogワークスペースを同期します。

実装上のメリットは次のとおりです。

既存のOpenAPIリポジトリをそのまま使える
YAMLファイルを別形式に移行する必要がない
スペックからモックサーバーを生成できる
フロントエンドはバックエンド実装前にAPIレスポンスを使える
スペックからテストケースとアサーションを生成できる
ドキュメントが同じスペックから生成される

セットアップの詳細は、スペックファーストモードのガイドを参照してください。スペックファーストとデザインファーストの違いは、スペックファーストまたはデザインファースト：どちらのApidogモードを使用すべきか？で整理されています。

実践例：OpenAPI仕様からコントラクトテストを作る

例として、GET /orders/{orderId} エンドポイントを考えます。

Postmanでは、レスポンス検証を手動で書く必要があります。

// Postmanテストタブ：仕様とは別に管理される
pm.test("Status is 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Response has orderId", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property("orderId");
  pm.expect(json.orderId).to.be.a("string");
});

このテストは有効ですが、OpenAPI仕様と別管理です。

たとえば、仕様側で status と createdAt を必須フィールドに追加しても、Postmanコレクションを更新しなければテストは古いままです。

OpenAPI仕様では、次のようにレスポンススキーマを定義できます。

# Gitリポジトリ内のOpenAPIスニペット
# 例: openapi/orders.yaml

paths:
  /orders/{orderId}:
    get:
      summary: IDで注文を取得
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 注文が見つかりました
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"

components:
  schemas:
    Order:
      type: object
      required:
        - orderId
        - status
        - createdAt
      properties:
        orderId:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - shipped
            - delivered
        createdAt:
          type: string
          format: date-time

Apidogのスペックファーストモードでは、このOpenAPIスキーマがテストケースのコントラクトアサーションに反映されます。

たとえば、APIレスポンスから status が欠落した場合、仕様上は必須フィールドなのでテストは失敗します。手動でPostmanテストを更新する必要はありません。

OpenAPI仕様をGitで管理する方法については、GitでOpenAPIスペックをバージョン管理する方法を参照してください。

移行前に確認すべきガバナンス項目

StoplightとPostmanからApidogへ集約する前に、次の項目は実際の試用環境で確認してください。

レポート可視性権限

CIテストレポートを特定のチーム、プロジェクト、ロールに限定できるか確認します。

確認観点:

プロジェクト単位でレポートを分離できるか
チーム外メンバーがレポートを閲覧できないか
CI実行結果へのアクセス権を制御できるか

SSOとSCIMプロビジョニング

ApidogはSSOをサポートしています。ただし、実運用前にはIDプロバイダーと接続して次を確認してください。

SSOログインの挙動
グループ同期
ユーザープロビジョニング
ユーザーの無効化・削除
権限の同期

SCIMの期待動作はSCIM RFCに定義されています。

プロジェクト間のスキーマ再利用

複数APIで共通の $ref スキーマを使っている場合、Apidogのワークスペースモデルが期待どおりに参照を解決できるか確認します。

特に、次のケースは移行前に検証してください。

components:
  schemas:
    User:
      $ref: "../common/schemas/user.yaml"

確認観点:

ファイル間 $ref が解決されるか
複数プロジェクトで共有スキーマを参照できるか
スキーマ更新時に影響範囲を追跡できるか

監査ログ

コンプライアンス要件がある場合は、監査ログの形式と保持期間を確認してください。

確認する内容:

スペック変更履歴
APIドキュメントの公開操作
テスト実行履歴
ユーザー権限変更
ログのエクスポート可否
保持期間

これらはApidogを避ける理由ではなく、統合プラットフォームを導入する際に必ず確認すべき実装要件です。

2つのツールを使い続けるべきケース

Apidogに集約するメリットは、仕様、モック、ドキュメント、テストを同じOpenAPIコントラクトに接続できることです。

ただし、次のような場合はStoplightとPostmanを使い続ける判断も合理的です。

Stoplight Docsの toc.json やカスタムドメイン設定が深く作り込まれている
技術ライターがStoplight中心のドキュメントワークフローを運用している
Postmanコレクションに大量の事前リクエストスクリプトがある
複雑な動的変数チェーンをPostmanで運用している
Postman Monitorを本番監視やオンコール通知に使っている

この場合は、移行コストと保守コストを比較します。

判断の目安は次のとおりです。

移行すべき可能性が高い:
仕様変更のたびにPostmanコレクションを手動更新している
QAが古いテストで失敗を調査している
OpenAPIとテストの差分確認に時間がかかっている

現状維持も検討:
Postmanスクリプト資産が大きい
Stoplight Docsの公開フローが組織に深く組み込まれている
監視・通知をPostman Monitorに強く依存している

Postman代替を広く比較したい場合は、APIテストに最適なPostmanの代替案も参考になります。

FAQ

ApidogはStoplight StudioのビジュアルOpenAPIエディタを置き換えられますか？

はい。ApidogにはOpenAPIスキーマ用のビジュアルフォームエディタがあり、リアルタイム検証とリントルールを使えます。

ただし、チームが .spectral.yaml によるカスタムSpectralルールへ強く依存している場合は、Apidog側で同等のルールをカバーできるか事前に確認してください。

Apidogは既存のGitHubリポジトリと同期できますか？

はい。Apidogのスペックファーストモードは、GitHubまたはGitLabリポジトリに接続し、OpenAPI仕様をコミットと同期します。

既存リポジトリを破棄する必要はありません。

APIスペックをGitで管理する考え方については、コードとしてのAPIスペックを参照してください。

ApidogはCIでCLIテスト実行できますか？

はい。ApidogにはCLIがあり、テストシナリオをCIで実行してレポートを出力できます。

現在 newman run を使っている場合は、Apidog CLIの実行コマンドに置き換える必要があります。NewmanのJSON出力を前提にした独自ダッシュボードがある場合は、レポート形式の違いも確認してください。

Postmanの事前リクエストスクリプトは移行できますか？

Apidogは事前リクエストスクリプトと動的変数をサポートしています。

ただし、Postmanの pm.variables.set() やカスタムJavaScriptを使っている場合、スクリプトは移植が必要です。ロジック自体は転用できることが多いですが、構文やAPIの違いは確認してください。

Apidogのスペックファーストモードは本番運用できますか？

スペックファーストモードは現在ベータ版です。

コア機能は利用できますが、次のようなケースは事前に概念実証で確認してください。

大規模モノレポ内のOpenAPI仕様
複数ファイルにまたがる $ref
ネストされたスキーマ参照
CIステータスレポート
チーム別の権限管理

本番展開前に、実際のリポジトリとAPI仕様で検証することをおすすめします。

結論

StoplightとPostmanの組み合わせは、API設計とAPIテストの両方をカバーできます。ただし、仕様とテストが別ツールに分かれるため、同期漏れ、重複メンテナンス、請求ラインの増加が発生しやすくなります。

Apidogのスペックファーストモードを使うと、Git上のOpenAPI仕様を信頼できる情報源にしたまま、ドキュメント、モック、テスト、CI実行を同じワークスペースに接続できます。

移行を検討する場合は、まず次を小さく検証してください。

既存のOpenAPIリポジトリをApidogに接続する
主要エンドポイントのモックを生成する
スキーマベースのテストを作成する
CIでApidog CLIを実行する
SSO、権限、監査ログを確認する

Apidogのスペックファーストモードを試すには、GitHubまたはGitLabからOpenAPIリポジトリを接続し、同じスペックからライブドキュメントとモックサーバーを生成します。Apidogをダウンロードして概念実証を開始するか、スペックファーストモードのページを確認してください。

DEV Community