PostmanコレクションとOpenAPI Spec、どちらを使うべきかという問いは、チームのエンジニア数が数人を超えたときに常に浮上します。6ヶ月前に作成したコレクションを開くと、今では必須フィールドが3つ追加され、非推奨のパラメーターが2つあり、レスポンスの形式がサーバーが実際に返すものと一致しなくなっていることに気づくでしょう。Git上のOpenAPI Specは異なることを示し、Swagger UIはさらに別のことを示しています。どれが正しいのか、誰も確信が持てません。
この「ずれ」はツール側の問題ではありません。ワークフローの問題であり、この違いは重要です。Postmanは、リクエストの実行、スクリプト作成、探索的テストに優れたツールです。問題は、チームがコレクションをAPI契約自体として扱い、その契約から派生した成果物の一つとして扱わない場合に生じます。
ボタン
なぜそもそもコレクションは乖離するのか
Postmanコレクションは、リクエストファーストの成果物です。リクエストを発行し、レスポンスを観察し、それを保存します。時間が経つにつれて、プリリクエストスクリプト、変数置換、テストアサーション、そしてAPIが正式に指定するものではなく、チームがAPIについて考える方法を反映するフォルダ構造を追加していきます。
対照的に、OpenAPI Specはコントラクトファーストの成果物です。これは、パス、パラメーター、スキーマ、レスポンスタイプを機械可読な形式で宣言し、ツールがそれらを検証、モック、およびコード生成できるようにします。
これら2つの成果物は、異なる問いに答えます。コレクションは「今日このエンドポイントをどのように呼び出すか？」に答え、Specは「このAPIは何をすべきか？」に答えます。チームが両方を独立して維持すると、必然的に乖離が生じます。ある開発者はプルリクエストをマージする際にSpecを更新し、別の開発者はテストが壊れていることに気づいたときにコレクションを更新します。誰もそれらをマージしません。数ヶ月のうちに、同じAPIの部分的に正確な説明が2つ存在し、どちらがより最新であるかを判断する信頼できる方法がなくなります。
このパターンに関する顧客からの証拠は具体的です。Inventis Koreaはまさにこの問題を報告しました。彼らのチームはAPIを構築し、Swagger用のOpenAPI Specを生成し、テストのためにコレクションをPostmanにインポートした後、3つの表現を同期させるために継続的な努力を費やしました。コレクションが完全なスキーマを反映していなかったため、テストはエッジケースを見逃しました。Specがテスト作成の入力ではなかったため、ドキュメントは乖離しました。これらは特殊なケースではなく、大規模なリクエストファーストのワークフローにおける予測可能な結果です。
根本原因：PostmanはSpecストアとして設計されていない
Postmanコレクションには独自のフォーマットがあります。Postmanコレクションスキーマは、リクエスト、スクリプト、およびフォルダ階層を記述する独自のJSON構造です。これはOpenAPIではありません。PostmanはOpenAPIをインポートおよびエクスポートできますが、変換は両方向で損失を伴います。OpenAPIからコレクションへの変換では、リクエストとして表現できないスキーマの詳細が失われ、コレクションからOpenAPIへの変換では、Specフィールドとして表現できないスクリプトやデータが失われます。
これはPostmanへの批判ではありません。これは、このツールが実際に何のためにあるのかを説明するものです。Postmanは、リクエスト中心のモデルを中心に構築されたコラボレーション機能を備えたリクエストランナーです。これを正規のAPI記述として使用するには、フォーマットが設計されていない構造を強制する必要があります。
単一のエンドポイントに対する2つの表現を比較してみましょう。
| プロパティ | Postmanコレクション | OpenAPI Spec |
|---|---|---|
| リクエストパラメータ | オプションの説明付きキーと値のペアとして保存される | 型指定され、検証され、requiredおよびschemaフィールドを持つ |
| レスポンスの形状 | 保存された例としてキャプチャされる（オプション） | パス全体で$refを再利用するJSONスキーマとして定義される |
| エラーレスポンス | リクエストごとに手動で追加される | 共有components/schemasと共にresponsesで列挙される |
| スキーマの再利用 | なし。リクエスト間でコピー＆ペースト | バリデーターによって強制されるcomponents/schemasへの$ref |
| 機械可読な契約 | いいえ | はい。ツールはサーバー、クライアント、モックを生成できる |
| Git diffフレンドリー | 不透明なIDを持つJSON。意味のあるレビューが難しい | YAML。意味のある行レベルの差分 |
| Lintと検証 | ネイティブ形式では不可 | Spectral、Redocly CLIなど |
この表は、なぜ乖離が発生するのかを示しています。コレクションは契約を完全に表現できないため、契約は別の場所に存在し、どちらか一方を編集するとすぐに両者が同期しなくなります。
Postmanチームにとっての「Specファースト」とは
Specファーストとは、「コードを書く前にすべてをYAMLで設計する」という意味ではありません。コレクション中心のワークフローから移行するほとんどのチームにとって、それは依存関係を逆転させることを意味します。Specファーストの方法論では、OpenAPIドキュメントをAPIの信頼できる記述としてGitに配置します。テストに使用するコレクションを含む、他のすべての成果物は、そのドキュメントから派生したものであり、逆ではありません。
実際には、ワークフローは次のようになります。
- SpecはGitにコミットされ、PRプロセスの一部としてレビューされます。
- テスト、モック、およびドキュメントはSpecから生成されます。
- APIが変更されると、まずSpecが変更されます。下流の成果物は自動的に、またはツールを介して更新されます。
- チームが探索的テストに使用するコレクションはSpecから生成されるため、常に現在の契約を反映します。
コレクションはまだ存在します。スクリプト、データ駆動型テスト、環境変数もまだ存在します。違いは、コレクションがSpecの上流ではなく、下流にあることです。Specに新しいフィールドが登場すると、生成されたコレクションにもそれが表示されます。Specからフィールドが削除されると、生成されたリクエストにそれが含まれなくなるため、テストは失敗します。乖離は、6か月後に発見されるのではなく、CIの失敗として現れます。
Specからコレクションを生成する方法
OpenAPI SpecからPostman互換のコレクションを派生させる方法はいくつかあります。ここでは、Redocly CLIで機能する例を示します。
# Install Redocly CLI
npm install -g @redocly/cli
# Validate the spec first
redocly lint openapi/petstore.yaml
# Bundle the spec (resolve $ref chains)
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
# Convert to Postman collection v2.1 using the openapi-to-postmanv2 library
npm install -g openapi-to-postmanv2
openapi2postmanv2 \
--spec dist/petstore-bundled.yaml \
--output dist/petstore-collection.json \
--prettyPrint
出力は標準のPostmanコレクションJSONです。これをPostmanにインポートするか、NewmanまたはPostman CLIのベースコレクションとして使用します。プリリクエストスクリプトと環境変数は独立して維持する別のファイルとして残ります。更新された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: |
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: |
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の変更は、Specを変更した同じPRで捕捉されます。
このワークフローにおけるApidogの役割
Apidogの価値は、Postmanをリクエストランナーとして置き換えることではありません。OpenAPI Specとチームが使用する他のすべての成果物を、手動変換ステップなしで接続することにあります。Git内のSpecが信頼できる情報源であり続け、Apidogはそれの上に構築されたコラボレーションおよび実行レイヤーです。
ApidogのSpec-Firstモード（現在ベータ版）では、GitリポジトリからOpenAPI SpecをApidogワークスペースに直接同期できます。同期されたSpecから、自動生成されたモック、インタラクティブなドキュメント、テストシナリオが得られ、SpecがGitで変更されるとすべて自動的に更新されます。Specと並行して別のコレクションを維持する必要はありません。SpecがApidogが表示し実行する内容を駆動します。
これは、STCグループと世界経済フォーラムが指摘したような状況を経験するチームにとって重要です。テスト用にPostmanを、Specレンダリング用に別のドキュメントツールを、フロントエンド開発用にモックサーバーを維持し、これら3つのシステムすべてが同じAPI契約を反映する必要がある場合です。Specが変更されると、1箇所で更新するだけで、これら3つのインターフェースすべてが更新されます。Apidogのワークスペース権限とSSOの粒度が、特にDHLの展開で説明されているような大規模チーム（100人以上のユーザー）の特定のアクセス制御要件を満たしているかどうかを試用版で確認する価値があります。これらは、概念実証における意味のある評価質問です。
移行パスについては、既存のPostmanコレクションをApidogに変換して出発点とし、そこからSpecを正規のドキュメントとして進めることができます。機械的なインポートステップは、リンクされたガイドで詳細に説明されています。
GitワークフローでSpecをコードとして扱う
API Spec as Codeアプローチとは、OpenAPIドキュメントがアプリケーションコードと同じ扱いを受けることを意味します。プルリクエスト、コードレビュー、CIでのリンティング、リリース境界でのバージョンタグなどです。ほとんどのチームは、すでにこのためのインフラストラクチャを持っていることに気づくでしょう。不足しているステップは、それをSpecファイルに適用することです。
役立ついくつかの実践事項：
- Specを、それを記述するサービスと同じリポジトリに保存し、別個の「docs」リポジトリには保存しない。これにより、Specの変更がコードの変更と同じPRで行われることが保証されます。
- CIパイプラインにSpectral lintステップを追加する。Spectralは、OpenAPI仕様とチームが定義するカスタムルールに対してSpecを検証します。壊れたスキーマ参照、説明の欠落、一貫性のない命名は、レビューコメントではなくCIの失敗となります。
- 破壊的変更には、アプリケーションコードを分岐させるのと同じ方法で、ブランチベースのSpec開発を使用する。ApidogワークスペースはSpecのブランチングをサポートしているため、異なるチームが安定したブランチに対して作業でき、同時に破壊的変更がレビューされます。
- 下流のコンシューマーリポジトリでSpecのバージョンをピン留めする。サービスBが契約テストのためにサービスAのSpecに依存する場合、mainのHEADではなく、特定のバージョンタグを参照する必要があります。
このアプローチは、新しいプロジェクトのステップバイステップのセットアップが必要な場合、git-native APIワークフローガイドで詳細に説明されています。
FAQ
Postmanの使用を完全にやめる必要がありますか？
いいえ。方法論の変更は、ツールの置き換えではなく、依存関係の方向性に関するものです。探索的テストやスクリプト作成のためにPostmanを使い続けることができます。違いは、コレクションが個別の成果物として維持されるのではなく、各テスト実行前にSpecから生成されることです。チームが探索的作業のためにPostmanのUIを好む場合でも、その好みはSpecファーストのワークフローと互換性があります。
既存のPostmanスクリプトと環境変数はどうなりますか？
プリリクエストスクリプト、テストスクリプト、および環境変数の定義は、生成されたコレクションの一部ではありません。これらは独立して維持する別個のファイルです。更新されたSpecからコレクションを再生成しても、スクリプトは上書きされません。構造レイヤー（リクエスト定義）が常にSpecから派生する一方で、挙動レイヤー（スクリプト）は保持されます。
まだSpecにないエンドポイントはどのように扱いますか？
Specファーストのワークフローでは、Specにないエンドポイントはテストの準備ができていません。これは厳しく聞こえるかもしれませんが、それがポイントです。Specゲートは、テストが作成される前に新しいエンドポイントが正式に記述されることを保証します。探索的開発の場合、ローカルスタブに対して作業し、エンドポイントを導入するPRの一部としてSpecエントリを追加することができます。最高のOpenAPIバリデータツールガイドを参照して、Specファーストの編集ステップを高速化するツールを見つけてください。
Apidog Spec-Firstモードは現在利用可能ですか？
Apidog Spec-Firstモードは現在ベータ版です。Apidogを通じてアクセスし、Git同期ワークフロー、ブランチサポート、自動生成モックがチームの要件を満たしているかどうかを評価できます。ベータ機能であるため、本番ワークフローとしてコミットする前に、特定のSpec構造に対してテストする価値があります。
これとSpecをPostmanにインポートすることとの違いは何ですか？
PostmanはOpenAPI Specをインポートし、そこからコレクションを生成できます。これは一度限りの変換です。その後、コレクションはSpecとは独立して維持されるため、すぐに乖離が再開されます。Specファーストのワークフローでは、CI実行（または同期）のたびにSpecからコレクションが再生成されるため、コレクションがSpecよりも古くなることはありません。
結論
チームが直面している乖離の問題は、Postmanのバグではありません。それは、部分的に重複する2つのAPI記述を、それらの間に明確な依存関係を持たせずに維持することの予測可能な結果です。解決策は、Git内のOpenAPI Specを信頼できる情報源として確立し、PostmanコレクションをそのSpecの下流にある生成された成果物として扱うことです。
この逆転により、何が、いつ壊れるかが変わります。テストを壊すSpecの変更は、それを引き起こしたPRで捕捉されます。ドキュメント、モック、テストシナリオはすべて同じソースから読み取られるため、常に同期が保たれます。2つのシステムを同期させるというメンテナンスの負担は、システムが1つになるためなくなります。
Apidogをダウンロードし、既存のOpenAPI SpecでSpec-Firstモードワークスペースを開いてください。Specではなくコレクションから始める場合は、コレクションをOpenAPIの出発点としてインポートし、そこからSpecファーストで作業を進めることができます。意図的に作られた例ではなく、自分のAPIに対して実行されるGit同期ワークフローを見れば、その実用性が明確になるでしょう。
ボタン