概要
Postmanユーザーの皆さんは、コレクションについてご存知かと存じますが、このコレクションには標準化されたフォーマットが存在し、オープンソースとして公開されています。Postmanコレクションは、PostmanにおいてAPIリクエストやテスト内容を記述するためのJSONベースのフォーマットです。
APIの開発・管理では、仕様をしっかり定義して、チームや外部の開発者と共有することが大切です。そんなときに広く利用されている標準フォーマットの一つに皆さんご存知のOpenAPIがありますが、今回紹介するPostmanコレクションもAPI仕様管理の有力な選択肢の一つとなり得ます。
本記事では、OpenAPIとPostmanコレクションを比較しながら、PostmanコレクションをAPI仕様管理にどのように活用できるかについて詳しく解説します。
TL;DR
-
OpenAPIとPostmanコレクションはそれぞれ異なる目的や強みを持ったAPI仕様フォーマット
- API仕様の設計・ドキュメント化はどちらでも実現可能
- API利用のオンボーディングを効率化するなら、実行可能なドキュメントを提供できるPostmanコレクション
- APIの標準仕様であることから、API仕様の流通性やエコシステムに強いのは OpenAPI
- APIテスト・自動化を重視するなら、複雑なテストも単一ツールで実現可能な Postmanコレクション
- OpenAPIとPostmanコレクションは相互変換が可能 (PostmanコレクションはOpenAPIの情報を包含しながら追加でテスト関連情報を持つため、Postman→ OpenAPIの場合は、テストスクリプトや変数などPostmanのみが持つ情報は反映されないことに注意)
-
単一のツールセットでAPI設計〜運用まで一連のAPIライフサイクル管理を実現したり、利用者オンボーディングを効率化したい場合はPostmanコレクションがより実用的な選択肢
目的と用途の違い
| OpenAPI | Postmanコレクション | |
|---|---|---|
| 主な目的 | API仕様の設計・ドキュメント化 | APIライフサイクル管理（仕様の設計・ドキュメント化、APIリクエスト送信・モック・テスト・自動化） |
| 主な用途 | API設計、SDK/サーバーコード生成、仕様管理 | APIドキュメント、テスト・自動化、チームコラボレーション |
OpenAPIとは？
OpenAPI（旧Swagger）は、API設計や仕様を標準化するための業界標準フォーマットです。YAMLまたはJSON形式で、エンドポイント、パラメータ、リクエスト/レスポンスのスキーマなどを包括的に定義できます。特徴は以下のとおりです。
- API仕様を明確化する標準フォーマット
- 自動ドキュメント生成（Swagger UI, Redocなど）
- クライアントSDKやサーバースタブの自動生成
- 多くのAPIツールとの互換性
Postmanコレクションとは？
Postmanコレクション は、PostmanでAPIリクエストやテストの内容を整理・管理するためのJSONベースのフォーマットです。APIエンドポイントやリクエスト情報をまとめて保存し、テスト・モック・共有・自動化に役立ちます。しかし、それだけではありません。Postmanコレクションは、設計からテスト・運用までAPIライフサイクルにわたって一貫したワークフローでAPIの管理を可能にする強力かつPostmanの中心的なデータ単位です。
補足スライド (link)
なお、APIライフサイクルについてはここでは深堀りしませんが、APIライフサイクルにおける各ステージでのPostmanの活用についてはこちらの資料が参考になります。
ドキュメントの観点
-
OpenAPIはエコシステムが充実しており、自動ドキュメント生成や自動バリデーション、コード生成を幅広くサポートしています。さらに業界標準のフォーマットとして広く使われているため、ドキュメントの流通性が非常に高いことも大きなメリットです
-
Postmanコレクション は独自フォーマットのため、OpenAPIほどの流通性はないものの、実行可能なドキュメントとして機能し、Swagger UIやRedocなどの静的ドキュメントにはない利点を持ちます。PostmanのUI上でAPIを操作できるため、開発者が初めてAPIを触る際のハードルを下げ、TTFC（Time to First Call: 最初にAPIをコールするまでに必要な時間、オンボーディングの効率性を表す指標の1つ）の短縮にも貢献します
補足スライド (link)
テストの観点
-
OpenAPIではSwagger UIやRedocから簡易的にリクエストを送信できます。ただし、スクリプトを用いた柔軟なテストやリクエストの連携、変数の管理などには追加のツールが必要です
-
Postmanコレクションはフォーマットに変数やスクリプト、リクエストの実行順序を組み込めるため、柔軟なテストを行うことができます。複数のリクエストをチェーンでつなぎ、シナリオテストを構築することも同じツールの中で簡単にできます
補足スライド (link)
フォーマットの違い
| OpenAPI | Postmanコレクション | |
|---|---|---|
| データフォーマット | YAML / JSON | JSON |
| スキーマ定義 | 可能（components.schemasで詳細定義） | 可能（リクエストボディのスキーマとして定義可能） |
| 環境変数のサポート | 限定的 | 充実した環境変数機能 |
| リクエスト・レスポンスの管理 | API仕様の定義のみ | 実際のリクエストとレスポンスを保存可能 |
| テスト・自動化 | 別ツールとの連携が必要 | Postmanのスクリプト機能で実装可能 |
構造比較
下記比較イメージを見て分かるように、Postmanコレクションは、OpenAPIの情報を包含しながら、変数・APIテストスクリプト・実行順序に関する追加情報を持つことができます。そういう意味で、PostmanコレクションはOpenAPIの上位互換とも言えます。
両フォーマットの共通要素とPostmanコレクションがもつ追加情報を整理すると次のようになります。
共通する要素
- APIのエンドポイント情報（リクエストメソッド、URL、パラメータ、ヘッダー）
- リクエストとレスポンスのフォーマット（JSON Schema、データ型定義）
- 認証情報の定義（OAuth、API Key、Basic Auth など）
- APIの説明・ドキュメント（エンドポイントごとの説明、使用例）
Postmanコレクションが持つ追加情報
-
環境変数（Variables）
- OpenAPIは静的な仕様記述だが、Postmanコレクションでは環境変数を利用し、動的なリクエストが可能
- 例：異なる環境（開発、本番）でエンドポイントURLや認証トークンを変更可能
-
テストスクリプト（Pre-request / Post-response Script）
- OpenAPIではAPIの仕様を定義できるが、実際のリクエストの前後でどのような処理を行うかの記述はない
- Postmanでは、リクエスト実行前後にJavaScriptでテストスクリプトを設定可能
- 例：レスポンスのステータスコードチェック、動的な値の取得・設定など
-
リクエスト実行順序
- OpenAPIには、APIリクエストの実行順序を明示する仕組みはない
- Postmanコレクションでは、フォルダやリクエストを並べることで、APIフローを定義可能
- 例：認証 → ユーザー作成 → ユーザー情報取得 のようなシナリオを組める
-
認証フローの柔軟な管理
- OpenAPIにもセキュリティスキーム（securitySchemes）があるが、Postmanではトークンの自動取得・設定をPre-request Scriptで制御可能
- 例：OAuthトークンの取得・更新を自動化
サンプルフォーマット
シンプルなOpenAPI (3.0形式)とPostman Collection（v2.1形式）
OpenAPI (3.0形式)とPostman Collection（v2.1形式） のシンプルなサンプルを示します。どちらも「ユーザー情報を取得する」という機能に絞った最小限の例です。
ソースコード( openapi.yaml | postman-collection.json )
簡単な解説
- OpenAPI
- openapi: 仕様のバージョンを示します (例: 3.0.3)
- info: APIのメタ情報 (タイトル、バージョンなど) を定義します
- servers: APIが利用可能なサーバー（ベースURL）を示します
- paths: APIエンドポイントを定義する部分です。/users エンドポイントでは全ユーザーの一覧を取得し、/users/{id} エンドポイントではパスパラメータ id を指定して特定のユーザーを取得します
- components.schemas: 共通で利用するスキーマを定義する場所です。ここでは User というスキーマを定義し、id (整数) と name (文字列) を必須プロパティにしています
- Postmanコレクション
- info: コレクションの名称やID、Postmanのスキーマバージョンなどが含まれます
- item: コレクション内のリクエストを定義する配列です。このサンプルでは「Get All Users」と「Get User by ID」の2つのリクエストを含んでいます
- variable: base_url という変数を定義し、APIエンドポイントのベースURLを切り替えられるようにしています
Postmanコレクションのテストスクリプト付きサンプル
上記のPostmanコレクションサンプルに簡単なテストスクリプトを追加した例です。スクリプトを追加したGet All Usersのリクエストだけを抜き出しています。同リクエストに対して、レスポンスコードが 200 であるかを確認し、さらにレスポンス配列の要素数が 1 以上であることをテストしています。なお、下記イメージ右側は同スクリプトをPostmanアプリで表示したイメージです。
(ソースコード)
どちらを使うか？ - 目的に応じた選択
API開発の各フェーズやチームのニーズに合わせて、最適なフォーマットを選択することが大切です。これまでの説明を整理し、次のようにテーブルでまとめてみました。
| 目的 | OpenAPI | Postmanコレクション |
|---|---|---|
| API仕様の設計 | ○ | ○ |
| APIドキュメント化（＊1） | ○ | ○ |
| 流通性・エコシステム活用（＊2） | ○ | △ |
| テスト・自動化（＊3） | ✗ | ○ |
- ＊1: 共に○としているが、強みが異なる。OpenAPIを元にしたドキュメントは静的であるものの、多様なツールにより生成が可能。一方、Postmanコレクションを元にしたドキュメントは、利用者のオンボーディングを効率化する強力な実行可能なドキュメントであるものの、これはPostmanのツール内でのみ実現可能
- ＊2: OpenAPIを採用しているツールやサービスが多く、したがって仕様を流通させるのに大きな利点がある。一方Postmanコレクションの流通性はPostmanユーザーに限定される
- ＊3: OpenAPIはテストやその自動化のための情報を含んでいないという点で✗。しかし他のツールセットと組み合わせることでテストや自動化の実現は可能となる
ざっくりと、OpenAPIは仕様の流通性やエコシステムに利がある一方、Postmanコレクションはテスト・自動化に利があると言えます。
OpenAPIとPostmanコレクションの相互変換
PostmanはOpenAPIとの互換性があり、相互変換が可能です。
OpenAPI → Postmanコレクション
- Postmanのインポート機能を用いて、OpenAPIドキュメントをPostmanコレクションに変換できます
- このインポート機能はAPIとしても提供されているので自動化も可能です。OpenAPIのPostmanへのインポート・更新の自動化についてはこちらの記事が参考になります。
Postmanコレクション → OpenAPI
- Postman APIの Transform collection to OpenAPI で、PostmanコレクションをOpenAPIに変換できます
- ただし、テストスクリプトや環境変数などの情報は完全には反映されない点に注意が必要です
まとめ
TL;DRとほぼ同じ内容ですが繰り返します。
OpenAPIとPostmanコレクションは、それぞれ異なる目的や強みを持ったAPI仕様フォーマットです。互いの長所を組み合わせることで、API開発をより効率的かつ効果的に進められます。
- API仕様の設計・ドキュメント化はどちらでも実現可能
- API利用のオンボーディングを効率化するなら、実行可能なドキュメントを提供できる Postmanコレクション
- API仕様の流通性やエコシステムに強いのは OpenAPI
- APIテスト・自動化を重視するなら、複雑なテストも単一ツールで実現可能な Postmanコレクション
- OpenAPIとPostmanコレクションは相互変換が可能 (PostmanコレクションはOpenAPIの情報を包含しながら追加でテスト関連情報を持つため、Postman→ OpenAPIの場合は、テストスクリプトや変数などPostmanのみが持つ情報は反映されないことに注意)
単一のツールセットでAPI設計〜運用まで一連のAPIライフサイクル管理を実現したり、利用者オンボーディングを効率化したい場合はPostmanコレクションがより実用的な選択肢となります。
標準仕様としてAPI仕様の流通性を求める場合は、OpenAPIとうまく併用するのがよいでしょう。
自分たちの開発スタイルに合わせ、OpenAPIとPostmanコレクションを上手に併用したり、使い分けてみてください。