OpenAPIの仕様書から指定したPostman のコレクションを自動更新するDockerイメージを作ったので紹介します
はじめに
バックエンド開発に携わる方であれば、API の設計やテストで「Postman」を利用する機会が多いのではないでしょうか。
今回は Postman と OpenAPI を活用している開発者向けに、OpenAPI の仕様書からコレクション ID に紐づく Postman のコレクションを自動更新できる Docker イメージを作成したので、紹介します。
なお、今回作成した Docker イメージは Docker Hub に公開しているので、ご自由にお使いください 🙌
対象読者
- Postman と OpenAPI を利用している・したことある方
- バックエンドの開発に携わっている・これから携わりたい方
- タイトルを見て興味を持った方
紹介すること・しないこと
（すること）
- Postman の簡単な説明とコレクション機能について
- 今回作成したコンテナの利用方法
（しないこと）
- Postman の使い方
- OpenAPI について
Postman の詳しい説明や使い方、OpenAPI については触れないので、参考記事や書籍を載せておきます。
Postman
OpenAPI
前置き
本題に入る前に、「Postman」 と 「OpenAPI 仕様書から Postman のコレクションを生成する機能」について紹介します。
「使い方だけ知りたい」という方は、本題のセクションまで読み飛ばしてください。
Postman について(ざっくり解説)
Postman は、Web API の設計・開発・テストに使われる GUI ツールです。
主に以下の機能を持ち合わせています。
- API リクエストの送信: HTTP リクエスト（GET, POST, PUT, DELETE など）を簡単に作成して送信できる
- レスポンスの確認: API から返ってくるレスポンスデータ（ステータスコード含む）を確認できる
- コレクション管理: 複数の API リクエストを一つのプロジェクトとして保存、整理することが可能。
- 自動テスト: リクエストの結果に基づいて自動テストを行うスクリプトを作成できる。
- 環境変数の利用: 開発、テスト、本番環境などで異なる設定を簡単に切り替えるために、環境変数を設定できる。
OpenAPI 仕様書から Postman のコレクションを生成する機能
Postman の コレクション機能では、「複数の API リクエストを管理することができる」と説明しましたが、OpenAPI の仕様書をインポートすることで自動的にコレクションを生成することが可能です。
Integrate Postman with OpenAPI | Postman Learning Center
主にバックエンドの開発で、OpenAPI generatorを利用していたり、「コードから OpenAPI の仕様書を自動生成する」系のライブラリを利用している場合、それらの仕様書を元に Postman のコレクションを生成し、そのまま API のテストを行うことができます...😚（便利）
環境変数とパスパラメーター
Postman では環境変数を設定することができ、リクエスト URL で{{pathparameter}}の形で定義すると、定義した環境変数の値が代入されます。
（環境変数の定義）
（リクエスト URL で環境変数を利用）
OpenAPI の仕様書から生成されたコレクションでは、PathParameter は:pathparameterの形で定義されています。
そのため、環境変数を利用するためには:pathparameterの形式から、{{pathparameter}}の形式に置き換えなければなりません。
さらに、OpenAPI の仕様書をインポートすると、毎回新しいコレクションとして作成されるため、更新があるたびに pathparameter の置き換える必要があります...😇 ﾒﾝﾄﾞｳ
本題
OpenAPI の仕様書をインポートしてコレクションを生成する機能の課題...
上記で述べた通り、OpenAPI の仕様書を Postman にインポートしてコレクションを生成する機能には下記の課題があります。
- 毎回新しいコレクションとして作成されるため、更新するたびに変数を用意する必要がある
- 共通のパスパラメーターの部分を毎回置き換えるのが面倒
例：「https://api.example.com/facilities/:facilityId/users」
→「https://api.example.com/facilities/{{facilityId}}/users」
上記の課題を改善するため、OpenAPI の仕様書さえあれば、コレクション ID に紐づいた Postman のコレクションを自動更新する Docker コンテナを作成しました。
用意するもの
- OpenAPI Specification ファイル
- Docker
事前準備
1. APIKey とコレクション ID を用意する
APIKey
Postman のプロフィール画面 → 「EditProfile」 → 「API Keys」
「Generate API Key」で APIKey を作成。
コレクション ID
コレクションの三点マーク「•••」→「Share（共有）」→ 「Via API(API 経由)」のタブを開く
https://api.postman.com/collections/{{collection_id}}?access_key=
の{{collection_id}}の部分がコレクション ID となります。
2. APIKey・CollectionID・PathParameter を環境変数として定義する
.env
POSTMAN_API_KEY=
POSTMAN_COLLECTION_ID=
OPENAPI_FILE_PATH=
PATHPARAMETERS=
| 環境変数名 | 説明 | 例 |
|---|---|---|
| OPENAPI_FILE_PATH | マウント先の OpenAPI 仕様書の path （/忘れずに） |
./internal/docs/openapi.json:/openapi.jsonとした場合OPENAPI_FILE_PATH=/openapi.json
|
| PATHPARAMETERS | Postman の変数に置き換えたい PathParameter（半角スペース区切り） | PATHPARAMETERS=facility_id position_id department_id team_id position_id |
docker compose を利用する場合
1. サービスを定義する
compose.yaml
services:
...（他のコンテナ定義）
postman_collection_update:
image: fukuemon/postman_collection_update
volumes:
- {{OpenAPI仕様書のpath}}:/openapi.json # 例：./docs/openapi.json:/openapi.json
env_file:
- .env
2. サービスの実行
docker compose run --rm postman_collection_update
単一のコンテナとして利用する場合
1. コンテナイメージをダウンロード・ローカルにビルドする
docker pull fukuemon/postman_collection_update
2. コンテナの実行
docker run --env-file .env -v $(pwd)/{{OpenAPI仕様書のpath}}:/{{OpenAPI仕様書のpath}} --rm postman_collection_update
例：
docker run --env-file .env -v $(pwd)/openapi.json:/openapi.json --rm fukuemon/postman_collection_update
実装方法について
実装方法ついては触れていませんが、OpenAPI の仕様書を Postman のコレクションに変換する npm パッケージ「openapi-to-postmanv2」を利用しています。pathparameter の変換については、パッケージに機能がなかったため、sedで置換する実装にしました。
既存ライブラリを拡張するような npm パッケージを作ろうとも考えましたが、バックエンドだと node を利用するケースは少なく、Docker で動かせる方が利便性が高い（CI/CD に組み込みやすいなど..）と考え、Docker での実装を選択しました。
最後に
Docker = 環境構築するためのものと思われがち（自分が前までそうでした...）ですが、今回のようにちょっとした自動化にも使えるので、もっといろんな活用方法を模索していきたいと思います。
冒頭でも紹介しましたが、今回作成した Docker イメージは Docker Hub に公開しています。
サンプルリポジトリ
サンプル用リポジトリも用意しているのでぜひお試しください！
それでは良き開発ライフを...👋
更新履歴
【9/30】docker-compose が非推奨になっているため修正
- docker-compose run --rm postman_collection_update
+ docker compose run --rm postman_collection_update
- docker-compose.yaml
+ compose.yaml
@sumiresakamotoさん、ありがとうございます 🙇🏻♂️
【10/01】サンプル用リポジトリを追加
Discussion