PostmanコレクションとOpenAPI SpecのどちらをAPI契約として扱うべきかは、チーム開発では避けて通れません。6ヶ月前のPostmanコレクションを開くと、必須フィールドが増え、非推奨パラメーターが残り、レスポンス例が実際のサーバー応答と一致しないことがあります。一方で、Git上のOpenAPI SpecやSwagger UIは別の内容を示している。こうなると、どれが正しいAPI仕様なのか判断できません。
この「ずれ」はツールの不具合ではなく、ワークフローの問題です。Postmanはリクエスト実行、スクリプト、探索的テストに強いツールです。しかし、チームがPostmanコレクションをAPI契約そのものとして扱うと、OpenAPI Specやドキュメント、テストとの同期が崩れます。
💡 依存関係を逆転させ、OpenAPI Specからコレクションを生成するようにすると、ずれを防げます。ApidogはこのSpec駆動型ワークフローをコラボレーション、モック、テスト、CI/CDに接続し、チームが同じソースから作業できるようにします。
なぜコレクションは乖離するのか
Postmanコレクションは、リクエストファーストの成果物です。
通常は次の流れで作られます。
- エンドポイントにリクエストを送る
- レスポンスを確認する
- リクエストを保存する
- プリリクエストスクリプトやテストアサーションを追加する
- 環境変数やフォルダ構造で整理する
この構造は「今日このエンドポイントをどう呼ぶか」を表すには便利です。
一方、OpenAPI Specはコントラクトファーストの成果物です。パス、パラメーター、スキーマ、レスポンス型を機械可読な形式で定義し、検証、モック、コード生成に使えます。
つまり、両者は答える問いが違います。
- Postmanコレクション: このAPIをどう呼び出すか
- OpenAPI Spec: このAPIは何を満たすべきか
チームが両方を独立して更新すると、必ずずれます。
たとえば、ある開発者がPRでOpenAPI Specを更新し、別の開発者がテスト失敗を見てPostmanコレクションだけを直す。誰も両者を突き合わせない。数ヶ月後には、同じAPIに対する2つの不完全な説明が残ります。
Inventis Koreaも同様の問題を報告しています。APIを構築し、Swagger用にOpenAPI Specを生成し、テスト用にPostmanへインポートした後、3つの表現を同期させるために継続的な手作業が必要になりました。コレクションが完全なスキーマを反映していないため、テストはエッジケースを見逃し、Specがテスト作成の入力ではないため、ドキュメントも乖離しました。
根本原因：PostmanはSpecストアではない
Postmanコレクションには独自フォーマットがあります。Postmanコレクションスキーマは、リクエスト、スクリプト、フォルダ階層を記述するJSON構造です。
これはOpenAPIではありません。
PostmanはOpenAPIをインポート・エクスポートできますが、変換には情報の欠落が発生します。
- OpenAPI → Postmanコレクション リクエストとして表現できないスキーマ情報が失われることがある
- Postmanコレクション → OpenAPI スクリプトや実行時データなど、Specに表現できない情報が失われる
これはPostmanへの批判ではありません。Postmanはリクエストランナーであり、探索的テストやスクリプト実行に適したツールです。しかし、正規のAPI契約ストアとして使うには限界があります。
| プロパティ | Postmanコレクション | OpenAPI Spec |
|---|---|---|
| リクエストパラメータ | オプションの説明付きキーと値のペアとして保存 | 型指定され、required や schema で検証可能 |
| レスポンスの形状 | 保存された例としてキャプチャされる | JSON Schemaとして定義され、$ref で再利用可能 |
| エラーレスポンス | リクエストごとに手動追加 |
responses と components/schemas で列挙 |
| スキーマの再利用 | 基本的にコピー＆ペースト |
$ref により再利用 |
| 機械可読な契約 | いいえ | はい。サーバー、クライアント、モック生成に利用可能 |
| Git diff | 不透明なIDを含むJSONでレビューしづらい | YAMLで行単位の差分を確認しやすい |
| Lintと検証 | ネイティブ形式では難しい | Spectral、Redocly CLIなどで可能 |
コレクションはAPI契約を完全に表現できません。そのため、契約は別の場所に存在する必要があります。問題は、その「別の場所」とコレクションを手動で同期しようとすることです。
PostmanチームにとってのSpecファーストとは
Specファーストとは、必ずしも「コードを書く前にすべてをYAMLで設計する」という意味ではありません。
Postman中心のワークフローから移行するチームにとっては、依存関係を逆転させることです。
Specファーストの方法論では、OpenAPIドキュメントをAPIの信頼できる記述としてGitに置きます。テスト、モック、ドキュメント、Postmanコレクションは、そのSpecから派生させます。
実装上の流れは次のとおりです。
- OpenAPI SpecをGitにコミットする
- PRでSpec変更をレビューする
- CIでSpecをlint・検証する
- Specからモック、ドキュメント、テスト、コレクションを生成する
- API変更時はまずSpecを変更する
- 下流の成果物を自動生成または同期する
コレクションは引き続き使えます。スクリプト、データ駆動型テスト、環境変数も残せます。
違いは、コレクションをSpecの上流に置かないことです。
Specに新しいフィールドが追加されると、生成されたコレクションにも反映されます。Specからフィールドが削除されると、生成されたリクエストからも消えるため、テストが失敗します。ずれは6ヶ月後ではなく、CIで検出されます。
SpecからPostmanコレクションを生成する
OpenAPI SpecからPostman互換コレクションを生成するには、Redocly CLIとopenapi-to-postmanv2を使えます。
# Redocly CLIをインストール
npm install -g @redocly/cli
# Specを検証
redocly lint openapi/petstore.yaml
# $refを解決してbundleを作成
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
# openapi-to-postmanv2をインストール
npm install -g openapi-to-postmanv2
# Postman collection v2.1に変換
openapi2postmanv2 \
--spec dist/petstore-bundled.yaml \
--output dist/petstore-collection.json \
--prettyPrint
生成されるのは標準のPostmanコレクションJSONです。Postmanにインポートすることも、NewmanやPostman CLIで実行することもできます。
プリリクエストスクリプトや環境変数は、別ファイルとして管理します。Specからコレクションを再生成しても、それらを上書きしない構成にします。
GitHub ActionsでSpec生成とテストを自動化する
CIに組み込むと、テスト実行前に常にSpecからコレクションを再生成できます。
# .github/workflows/api-tests.yml
name: API contract tests
on:
push:
paths:
- "openapi/**"
- "src/**"
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
npm install -g @redocly/cli openapi-to-postmanv2 newman
- name: Validate OpenAPI spec
run: redocly lint openapi/petstore.yaml
- name: Generate collection from spec
run: |
mkdir -p dist
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
openapi2postmanv2 \
--spec dist/petstore-bundled.yaml \
--output dist/petstore-collection.json
- name: Run tests against generated collection
run: |
mkdir -p results
newman run dist/petstore-collection.json \
--environment config/env-staging.json \
--reporters cli,junit \
--reporter-junit-export results/test-results.xml
- name: Upload test results
uses: actions/upload-artifact@v4
with:
name: test-results
path: results/
この構成では、Specがすべてのテスト実行の入力になります。
Spec変更によってテストが壊れる場合、その変更を入れたPRで検出できます。Postmanコレクションを手動更新する必要はありません。
Apidogをこのワークフローで使う位置づけ
Apidogの役割は、Postmanを単純に置き換えることではありません。
OpenAPI Specと、チームが使うモック、ドキュメント、テスト、コラボレーション機能を接続する実行レイヤーとして使えます。Git内のSpecを信頼できる情報源にし、その上にApidogのワークスペースを構築します。
ApidogのSpec-Firstモード（現在ベータ版）では、GitリポジトリからOpenAPI SpecをApidogワークスペースに同期できます。
同期されたSpecから、次の成果物を扱えます。
- 自動生成されたモック
- インタラクティブなAPIドキュメント
- テストシナリオ
- チーム向けの共有ワークスペース
SpecがGitで変更されると、Apidog上の内容も同期されます。Specと並行して別のコレクションを手動で管理する必要はありません。
これは、STCグループや世界経済フォーラムが指摘したような構成で特に重要です。
- テスト用にPostmanを使う
- Specレンダリング用に別のドキュメントツールを使う
- フロントエンド開発用にモックサーバーを使う
- それぞれが同じAPI契約を反映する必要がある
Specを1箇所で更新し、そこから各インターフェースを更新できれば、同期コストを大きく減らせます。
既存資産から始める場合は、PostmanコレクションをApidogに変換して出発点にできます。その後、OpenAPI Specを正規のドキュメントとして運用します。
GitワークフローでSpecをコードとして扱う
API Spec as Codeアプローチでは、OpenAPIドキュメントをアプリケーションコードと同じように扱います。
具体的には次のようにします。
- Pull Requestで変更する
- コードレビューする
- CIでlintする
- リリース時にバージョンタグを付ける
- 破壊的変更をブランチで管理する
多くのチームは、すでにこのためのGitインフラを持っています。必要なのは、それをSpecファイルにも適用することです。
実践しやすいルールは次のとおりです。
Specはサービスと同じリポジトリに置く
別のdocsリポジトリに分離すると、コード変更とSpec変更が別PRになりやすくなります。壊れた
$refや説明漏れをCI失敗にする
レビューコメントで人間が見つけるのではなく、自動検出します。破壊的変更はブランチで管理する
アプリケーションコードと同様に、安定ブランチと変更ブランチを分けます。下流のコンシューマーはSpecバージョンを固定する
サービスBがサービスAのSpecを契約テストに使う場合、mainのHEADではなく、特定のタグを参照します。
新しいプロジェクトでのセットアップ例は、git-native APIワークフローガイドで詳しく説明されています。
FAQ
Postmanの使用を完全にやめる必要がありますか？
いいえ。
変更するのはツールではなく、依存関係の方向です。探索的テストやスクリプト作成にはPostmanを使い続けられます。
ただし、コレクションを個別に保守するのではなく、各テスト実行前にSpecから生成します。Postman UIを使う運用と、Specファーストのワークフローは両立できます。
既存のPostmanスクリプトと環境変数はどうなりますか？
プリリクエストスクリプト、テストスクリプト、環境変数は、生成されたコレクションとは別ファイルで管理します。
- リクエスト定義: OpenAPI Specから生成
- 実行時の挙動: スクリプトや環境変数として維持
この分離により、Specからコレクションを再生成しても、既存のスクリプトを上書きせずに済みます。
まだSpecにないエンドポイントはどう扱いますか？
Specファーストのワークフローでは、Specにないエンドポイントはテスト対象として準備完了ではありません。
これは制約ではなく、ゲートとして機能します。新しいエンドポイントを追加するPRでは、実装と同じPRでSpecエントリも追加します。
探索的開発では、ローカルスタブに対して作業し、正式に導入するタイミングでSpecに反映します。編集や検証を高速化したい場合は、最高のOpenAPIバリデータツールを参考にできます。
Apidog Spec-Firstモードは現在利用可能ですか？
Apidog Spec-Firstモードは現在ベータ版です。
Apidogからアクセスし、Git同期ワークフロー、ブランチサポート、自動生成モックがチームの要件に合うか検証できます。
ベータ機能のため、本番ワークフローに組み込む前に、自分たちのOpenAPI Spec構造で試すことをおすすめします。
SpecをPostmanにインポートするだけでは不十分ですか？
PostmanはOpenAPI Specをインポートし、そこからコレクションを生成できます。
ただし、それは一度限りの変換です。その後、コレクションを手動で編集し始めると、Specとの乖離が再び発生します。
Specファーストのワークフローでは、CI実行や同期のたびにSpecからコレクションを再生成します。そのため、コレクションがSpecより古くなることを防げます。
結論
PostmanコレクションとOpenAPI Specの乖離は、Postmanのバグではありません。部分的に重複する2つのAPI記述を、明確な依存関係なしに維持することの結果です。
解決策はシンプルです。
- Git内のOpenAPI Specを信頼できる情報源にする
- PostmanコレクションをSpecの下流成果物として生成する
- CIでSpec検証とコレクション生成を自動化する
- ドキュメント、モック、テストを同じSpecから派生させる
この構成にすると、壊れるタイミングが変わります。Spec変更によってテストが壊れる場合、そのPR内で検出できます。ドキュメント、モック、テストシナリオは同じソースを参照するため、手動同期の負担が減ります。
Apidogをダウンロードし、既存のOpenAPI SpecでSpec-Firstモードのワークスペースを試してください。コレクションから始める場合は、PostmanコレクションをOpenAPIの出発点としてインポートし、そこからSpecファーストの運用に切り替えられます。
Top comments (0)