はじめに
OpenAPIをAPI仕様のマスターとしてGitHubで管理しているプロジェクトにおいて、仕様変更はGitHubのPull Request（以下、PR）を通じて反映し、PostmanのSpec Hubを活用してPostmanコレクションを生成・公開するフローを紹介します。
Spec Hubは、2025年4月にリリースされたばかりの新しい機能で、OpenAPIなどのAPI仕様をチームで効率的に作成・管理・共有できる、PostmanのAPI設計支援機能です。
Spec Hub活用パターンの強み
以前、以下の記事にてPostmanコレクションとGitHubの連携機能を活用し、OpenAPIベースのプロジェクトで、GitHubのPRを通じてPostmanコレクションを自動更新・公開する方法をご紹介しました。
この方法では、OpenAPIファイルを更新すると、それを元にPostmanコレクションが再生成され、その内容が自動的に反映されます。ただし、このフローには1つ大きな制約があります。コレクションに追加したテストスクリプトやコメントなどの補足情報は、OpenAPI更新時に上書きされてしまい、失われてしまうのです。
一方、本記事で紹介するSpec Hubを活用したアプローチでは、こうした制約を回避できます。GitHubのPRでOpenAPI仕様を更新すると、それに応じてSpec Hub上のOpenAPIも更新されます。そこから生成されるコレクションは、既存のスクリプトや設定を保持したまま更新が可能です。そのため、APIドキュメントとしての利用にとどまらず、テストや自動化といったPostmanの強力な機能を活用した実践的なフローが実現できます。
このように、前回紹介した方法に比べ、Spec Hubを活用することでより柔軟で実用的なフローが可能となるため、本フローを積極的に押していきたいと考えてます。
OpenAPI更新からコレクション公開までのフロー
まず、フローを分かりやすくするために、一枚の図にまとめました。
図: OpenAPIベースプロジェクトのコレクション更新・公開フロー
ここで紹介する例では、「Todo API」を開発するチームが、APIの仕様としてGitHub上でOpenAPI Specファイルを管理しています。この仕様をもとにPostmanコレクションを生成し、社内利用や外部向けのAPI公開に活用しています。
新機能の追加や仕様変更の際には、メンバーがmainブランチからfeatureブランチを切って開発を行い、変更が完了したらPRを作成し、レビュー後にmainブランチへマージするという開発フローを採用しています。
そして、ここで紹介する手順では、OpenAPIの更新時にPostman上のSpec HubのOpenAPI定義を自動生成していきたく、OpenAPIを更新するためのPRをmergeする際に、これを実現するGitHub Actions (以下、GHA)の設定を行います。
次のようなフローになります：
- [初回のみ] 事前準備
- プライマリーワークスペース（インターナル）のSpec HubにOpenAPIファイルをインポートする
- OpenAPIを更新するためのPRをmergeする際に、Spec HubのOpenAPI定義を更新するGHAをリポジトリに設定
- mainブランチからfeatureブランチを作成（または、リポジトリに書き込み権限がない場合はForkでもOK）
- featureブランチのOpenAPIファイルを更新
- GitHubでPRを作成するチームでレビュー後、変更をmainブランチにマージ。OpenAPIがマージされると、GHA経由でプライマリーワークスペースのSpec HubのOpenAPIに自動同期される
- 更新されたSpec HubのOpenAPIを元に、コレクションを更新（または、生成）する
- [初回のみ] プライマリーコレクションをパブリックワークスペースへFork（このときGitHubブランチとの接続は行わない）
- その後、プライマリーコレクションに変更が発生した場合、パブリック側のForkコレクションでPullして取り込む
これから、フローの詳細を解説していきます。
なお、ここでテストに使用するGitHubリポジトリには、次のようにAPIサーバーのソースコードとOpenAPI定義ファイルが含まれています。
図: リポジトリのファイル構成（連携前）
Step1: 事前準備
1-1. OpenAPIをインポート
プライマリーワークスペースに、mainブランチのOpenAPIをインポートします。Postmanでは、OpenAPI 3.0と3.1をインポートでき、YAMLとJSONの両方のフォーマットをサポートしてます。
OpenAPIをPostmanにインポートするには、サイドバーのインポートを選択します。すると、次のようなインポート用のモーダルが立ち上がります。ここで、今回インポートするOpenAPIファイル（Todo API用Open API）を指定します。
図: インポートモーダル
次にインポート方法の選択をします。ここでOpenAPI 3.0 Specification with a Postman Collectionを選択します。
図: インポート方法の選択
これで、プライマリーワークスペースのSpec Hubにはここで指定したOpenAPIがインポートされ、さらにこのOpenAPIをベースにプライマリーコレクションが生成されます。なお、今後このSpec HubのOpenAPIを更新すると、1クリックでその変更をコレクションに反映できます。後述の「Step5: SpecHubのOpenAPIを元にコレクションを更新」ではまさにこの機能を活用します。
図:インポートで生成されたOpenAPI Specとコレクション
次に、Spec HubにインポートされたOpenAPIのSpec ID (Specification ID)を取得します。右サイドバーの(i)アイコンをクリックすると下記のようなSpecification IDが表示されます。このSpec IDは次の1-2で設定するGitHub Actionの処理で必要になります。
図: Specification IDの表示
1-2. OpenAPIをSpecHubに同期させるGitHub Actions設定
下記のGHAファイル(sync-openapi-to-postman-spechub.yml)をmainブランチの.github/workflows配下に配置します。これで、feature -> mainブランチへのPRがmergeされると、OpenAPIに変更があった場合にのみ、それを元にSpec HubのOpenAPIが更新されるようになります。
name: Sync OpenAPI to Postman SpecHub
on:
push:
branches:
- main # trigger push to main branch
env:
OPENAPI_FILE: oas/openapi.yaml # Path to your OpenAPI file
POSTMAN_SPEC_ID: "501b63dc-660d-4707-82e2-84e59cfb6024" # Your Postman Spec ID
jobs:
sync-openapi:
runs-on: ubuntu-latest
steps:
- name: Checkout main branch
uses: actions/checkout@v3
- name: Check for changes in openapi.yaml
id: detect_change
run: |
git fetch origin main
CHANGED=$(git diff --name-only HEAD~1 HEAD | grep "$OPENAPI_FILE" || true)
echo "changed_files=$CHANGED" >> $GITHUB_OUTPUT
- name: Exit if no changes detected
if: steps.detect_change.outputs.changed_files == ''
run: |
echo "No changes detected in $OPENAPI_FILE. Exiting workflow."
exit 0
- name: Sync OpenAPI to Postman SpecHub
uses: yokawasa/action-sync-openapi-to-postman-spechub@v0.1.0
with:
postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
postman-spec-id: ${{ env.POSTMAN_SPEC_ID }}
openapi-file-path: ${{ env.OPENAPI_FILE }}
openapi-format: "yaml"
このGHAに必要な情報はずばり次の3つです:
- Spec ID: 更新対象のSpec Hubで管理するOpenAPIのSpecification ID。1-1で取得した値をenvブロックで定義するPOSTMAN_SPEC_IDに設定します
-
Open APIファイルのパス: GitHubリポジトリで管理する更新元となるOpenAPIファイルのパス（ここでは
oas/openapi.yaml）。これをenvブロックで定義するOPENAPI_FILEに設定します - Postman APIキー: Postman APIを利用するのに必要なAPIキー。このページを参考にPostman APIキーを取得してください。なお、Postman APIキーは秘匿情報にあたるので、GitHubリポジトリのシークレットとして登録してGHAで活用するようにしてください
なお、Spec HubのOpenAPIとの同期部分は拙作のsync-openapi-to-postman-spechubというActionを使ってます。
Step2: mainブランチからfeatureブランチを作成
mainブランチからfeatureブランチを作成します。リポジトリに書き込み権限がない場合はForkでも大丈夫です。
GitHubリポジトリのページでブラウザから操作してもいいですし、コマンドの方は次のようにfeatureブランチ(ここでは、feature-1)を作成します。
# 事前にやっておくこと
git checkout main # mainブランチに切り替え
git pull origin main # 最新のmainブランチを取得
# mainブランチからfeatureブランチ（`feature-1`）を作成
git checkout -b feature-1 main
Step3: featureブランチでOpenAPIファイル更新
featureブランチのOpenAPIファイルを更新します。
OpenAPIの定義に変更を加えた後に、変更ファイルをcommitして、アップストリームであるmainブランチにpushします。
git add oas/openapi.yaml
git commit -m "update openapi"
git push origin feature-1
Step4: GitHubでPRを通じてmainブランチにマージ
GitHub上でfeature-1→mainブランチのPull Requestを作成します。必要に応じてチームによるPRレビューを実施します。そして、レビューが完了し、PRがmergeされると、Step1で設定したGHAが発動し、OpenAPIを元にSpec HubのOpenAPIが自動更新されます。
図: PR作成 → merge → GHA経由でSpec HubのOpenAPI同期
Step5: SpecHubのOpenAPIを元にコレクションを更新
Step4で更新されたSpec HubのOpenAPIを元にプライマリーワークスペースのコレクションを更新します。
Spec HubのOpenAPIを選択し、右上のGenerate collectionの右隣をクリックすると次のように、このOpenAPIを元に生成されたコレクションが表示されます。ここでは、「1-1. OpenAPIをインポート」時にOpenAPIと一緒に生成されたTodo APIコレクションが表示されています。このコレクション名の隣に表示されているUpdateをクリックします。これで、OpenAPIの変更が該当コレクションに反映されます。
図: Update Collection from OpenAPI in Spec Hub
Step6-7: コレクション公開
プライマリーコレクションをパブリックワークスペースにForkし（この際、GitHubブランチとの接続は行いません）、そのコレクションを一般公開します。
公開後にプライマリーコレクションに変更が加わった場合は、パブリック側のForkコレクションで変更をPullすることで、その内容を反映できます。Pullのタイミングは任意に選べるため、公開後の更新を柔軟にコントロールできるのが特徴です。
この手順は、冒頭で紹介した記事の「コレクション公開のためのGitHub連携コレクションと公開用コレクションの同期フロー」で詳しく解説しています。
おわりに
本記事では、OpenAPIを中心に据えたAPI仕様管理と、PostmanのSpec Hubを組み合わせたコレクション生成・公開のフローを紹介しました。
従来の「OpenAPI → Postmanコレクション」の一方向な生成では難しかった、スクリプトの保持や柔軟なテスト活用が、Spec Hubを活用することで可能になります。また、GitHub Actionsと連携することで、PRベースでの変更管理も実現でき、より自然な形でCI/CDフローに組み込むことができます。
API開発における「仕様の信頼できる唯一の情報源（Single Source of Truth）」としてのOpenAPI、そして、チーム全体でのコラボレーションを支えるPostmanという両者の強みを生かすことで、保守性の高いAPIライフサイクルを構築できます。