01
入力の種類とモードを合わせる
方向を変更しても入力は自動で置き換わりません。モードごとのサンプルか対応するファイルを読み込んでください。コレクションは2.1の宣言、環境ファイルはvalues配列が必要です。
APIツール
Postmanコレクション変換引き継ぐ前に差分を確認
コレクション、仕様書、環境ファイルを選び、リクエスト一覧と変換レポートを確認してから書き出します。
Postmanコレクション変換
コレクション・仕様書・環境の入力
結果
入力はこのブラウザー内で処理します。API呼び出し、スクリプト実行、外部参照の取得は行いません。
出力設定
例に基づく変換であり、完全な契約ではありません。レポートと残ったプレースホルダーを確認してください。
500,000文字・深さ60・50,000ノード・1,000リクエスト・500件の報告・5秒。
結果が古くなりました。再検証後に出力できます。
コピーと保存は選択した表示の全件を出力します。マスクは出力だけに適用します。
Postmanコレクション変換が必要になるのは、動くリクエスト集を仕様書として共有したいときです。呼び出し例とAPIの契約は同じ情報ではありません。変換できた操作と、別途記述が必要な制約を分けて確認できます。
既存の仕様書からコレクションを作る場合も、元の文書を残してください。認証のプレースホルダー、レスポンス定義、スキーマの制約は、生成したリクエストだけでは再現できないことがあります。
Postmanコレクション変換をここで確認する理由
フォルダーから操作への対応が見える
Postmanコレクション変換は入れ子のフォルダーを再帰的に読み取り、その名前を操作のタグに残します。リクエスト一覧とレポートを切り替えると、読み取った呼び出しと省略したスクリプトを確認できます。同じパスとメソッドの重複は上書きせずエラーにします。
環境ファイルの秘密値を見直せる
環境設定の書き出しとコレクションの整形では、初期状態でマスキングが有効です。識別できた秘密値は出力側で置換し、無効な環境行は別途報告します。.envの行数が減った理由を一覧から確認できます。
書き出し前の三つの確認
02
再計算のタイミングを知る
自動変換は編集後350ms待って実行します。複数箇所をまとめて直したいときは自動をオフにし、Ctrl/Cmd + Enterで実行します。入力や設定を変えた直後はコピーと保存が無効になります。
03
表示と書き出しの対象を選ぶ
結果は変換文書、リクエストは全件の一覧、レポートはコードと参照元のパスを出力します。画面は50件ずつ表示しますが、ダウンロードには選んだ一覧の全件が含まれます。
OAS形式とリクエストの間を移す
正方向と逆方向を一つの画面で
Postman OpenAPI変換ではOpenAPI 3.0.3をJSONまたはYAMLで生成します。逆方向は3.0と3.1を読み込み、Collection 2.1を書き出します。OpenAPI Postmanコレクション間の移行に必要な操作情報のローカル参照も解決します。
サンプルから制約を決めつけない
クエリとヘッダーは文字列の例に、JSONボディは本文の例になります。一つのサンプルからrequiredやenumを追加しません。逆方向は明示的なexample、次にdefaultを利用し、値がなければ名前付きプレースホルダーにします。
認証方式とサーバーの優先順位
Basic、Bearer、ヘッダーまたはクエリのAPI Keyを対応付けます。逆変換は操作、パス、ルートの順でサーバーを選び、その先頭を使用します。複数候補や複雑な認証条件はレポートに残ります。
環境設定を独立して書き出す
Postman環境変数は独立した環境JSONから処理します。有効なスカラー値は文字列に、nullは空文字になります。空白や改行、ドル記号を保つ引用符を選び、不正なキーや重複はエラーにします。
再現できる範囲とできない範囲
- 受け付ける版は限定
- Collection 2.1とOpenAPI 3.0.x・3.1.xに対応します。Swagger 2.0、Collectionの他の版、OpenAPI 3.2は対象外です。2.1を最新のコレクション形式として扱うわけではありません。
- スクリプトや変数の実行環境は含まない
- 事前スクリプトとテストは実行しません。整形ではソースを保持し、変換では省略を報告します。動的変数の評価や、環境・グローバル・Vaultの値の自動統合も行いません。
- 完全な契約の往復ではない
- 逆変換ではレスポンス定義と検証制約を省略して報告します。複雑なパラメーターの直列化、コールバック、webhooks、OAuthフロー、署名、バイナリーファイル内容は対応範囲外です。生成した例が本番APIで有効とは限りません。
- 参照とサーバーは補完しきれない
- 外部参照を取得しません。ローカル参照が欠ける場合や仕様書が無効な場合は停止します。コレクションの基底変数を解決できないとサーバーを/にし、逆変換でサーバーがないとexample.invalidを使って報告します。
- 秘密値の検出には限界がある
- 機密名のキー、secret指定の変数、認証値、Cookie、URL認証情報を置換します。JSONボディは構造を調べ、その他のボディは全体をマスクします。説明やスクリプト中の任意の秘密は残る可能性があるため、出力を見直してください。
- 過大な入力は明示的に拒否
- 入力500,000文字、深さ60、50,000ノード、1,000リクエスト、500件の報告、結果全体2,000,000文字、処理5秒が上限です。重複キー、精度を失う数値、YAMLの別名・独自タグ・複数文書は受け付けません。
Postmanコレクション変換のよくある質問
YAMLとJSONのどちらの仕様書を読み込めますか？
OpenAPIからコレクションへのモードでは両方を読めます。コレクションと環境ファイルはJSONで入力します。形式の選択はOpenAPI出力だけに適用され、コレクションはJSON、環境設定は.envになります。
相互変換すると情報は失われますか？
はい。実行手順を持つコレクションと宣言的な仕様書は用途が違います。変換レポートを確認し、移行の出発点として使ってください。変換成功は認証やレスポンスの検証成功を意味しません。
生成するコレクションのbaseUrlはどう設定しますか？
操作、パス、ルートの順で選んだ有効なサーバーの先頭URLをbaseUrlに設定します。後続の操作には別の基底変数を使います。サーバー変数は既定値で展開し、サーバー不在ならexample.invalidを設定して報告します。
シークレット変数をエクスポート対象から外せますか？
マスキングを有効にすると、secret指定や機密名に合致した値を[REDACTED]に置換します。これはこの画面の出力を制御する機能で、Postman側の権限設定を変更しません。任意の文章中の秘密はすべて検出できるわけではありません。
コレクションのエクスポートに環境変数も含められますか？
自動では含まれません。環境JSONを別に書き出し、環境から.envへのモードで処理してください。そのファイルに含まれた有効な値だけを読み取り、存在しないローカル値やVaultの値を取得することはありません。
期待と違う結果になりましたか？