Postman OpenAPI Sync CLI

自動化 Postman Collection 與 OpenAPI 規格同步的命令列工具。

功能特色

• 🔄 自動同步 OpenAPI 規格到 Postman Collection
• 📦 備份現有 Postman Collection
• 🔀 智慧合併,保留自訂設定(測試指令碼、標頭、變數等)
• 🧪 執行 Newman 驗證集合
• 📊 產生詳細的變更報告
• 🚀 簡單易用的 CLI 介面

重要說明

⚠️ Collection 格式限制: 合併功能僅支援使用本工具的 converter 轉換或從 Postman 匯入時的 collection 格式。手動編輯的 collection 可能因資料夾結構不符合內建規則而無法正常合併。並且 converter 和 Postman 匯入的 collection 也會有細微差異。

系統需求

• Node.js 22.20.0 或更高版本 (較低版本未經測試, 可能無法正常運作)

安裝 Node.js

方法 1: 直接安裝

前往 Node.js 官方網站 下載並安裝適合您作業系統的版本。建議安裝 LTS (長期支援) 版本。

方法 2: 使用 nvm (推薦)

使用 nvm (Node Version Manager) 可以輕鬆管理多個 Node.js 版本:

Windows:

# 安裝 nvm-windows
# 從 https://github.com/coreybutler/nvm-windows/releases 下載安裝程式

# 安裝 Node.js LTS 版本
nvm install lts
nvm use lts

macOS/Linux:

# 安裝 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安裝 Node.js LTS 版本
nvm install --lts
nvm use --lts

確認安裝

安裝完成後, 可以在終端機執行以下指令確認版本:

node --version
npm --version

安裝

全域安裝

npm install -g postman-openapi-sync

本地安裝

npm install postman-openapi-sync

開發模式

git clone <repository-url>
cd postman-openapi-sync
npm install
npm link

設定

建立 .env 檔案並設定以下環境變數:

POSTMAN_API_KEY=your_postman_api_key
POSTMAN_COLLECTION_ID=your_collection_id
OPENAPI_PATH=./path/to/openapi.yaml
# REJECT_UNAUTHORIZED=false  # 選用: 允許自簽 SSL 憑證 (預設為 true)

使用方式

同步集合

將 OpenAPI 規格同步到 Postman Collection:

postman-sync sync --openapi ./openapi.yaml --collection <collection-id>

或使用環境變數:

postman-sync sync

備份集合

備份現有的 Postman Collection:

postman-sync backup --collection <collection-id>

備份檔案會儲存在 backups/ 目錄中,包含時間戳記。

轉換 OpenAPI

將 OpenAPI 規格轉換為 Postman Collection 格式:

postman-sync convert --openapi ./openapi.yaml --output ./output/collection.json

合併集合

合併兩個 Postman Collection,保留自訂設定:

postman-sync merge --original ./original.json --new ./new.json --output ./merged.json

驗證集合

使用 Newman 執行集合測試:

postman-sync validate --collection ./collection.json --environment ./env.json

命令列選項

sync

選項	簡寫	說明	預設值
--openapi <path>	-o	OpenAPI 規格檔案路徑	OPENAPI_PATH 環境變數
--collection <id>	-c	Postman Collection ID	POSTMAN_COLLECTION_ID 環境變數
--api-key <key>	-k	Postman API Key	POSTMAN_API_KEY 環境變數
--no-reject-unauthorized	無	停用 SSL 憑證驗證 (允許自簽憑證)	預設啟用憑證驗證

backup

選項	簡寫	說明	預設值
--collection <id>	-c	Postman Collection ID	POSTMAN_COLLECTION_ID 環境變數
--api-key <key>	-k	Postman API Key	POSTMAN_API_KEY 環境變數

convert

選項	簡寫	說明	預設值
--openapi <path>	-o	OpenAPI 規格檔案路徑	OPENAPI_PATH 環境變數
--output <path>	-d	輸出檔案路徑	./temp/converted-collection.json
--no-reject-unauthorized	無	停用 SSL 憑證驗證 (允許自簽憑證)	預設啟用憑證驗證

merge

選項	簡寫	說明	預設值
--original <path>	-o	原始集合檔案路徑	必填
--new <path>	-n	新集合檔案路徑	必填
--output <path>	-d	輸出檔案路徑	./temp/merged-collection.json

validate

選項	簡寫	說明	預設值
--collection <path>	-c	集合檔案路徑	./temp/merged-collection.json
--environment <path>	-e	環境檔案路徑	無

工作流程

完整的同步流程包含以下步驟:

1. 備份: 自動備份現有 Postman Collection
2. 轉換: 將 OpenAPI 規格轉換為 Postman Collection 格式
3. 合併: 智慧合併新舊集合,保留自訂設定
4. 報告: 產生詳細的變更報告
5. 更新: 將合併後的集合更新到 Postman

保留的自訂設定

同步時會保留以下自訂設定:

• ✅ 測試指令碼 (test events)
• ✅ 預請求指令碼 (prerequest events)
• ✅ 自訂標頭 (X-* headers)
• ✅ 集合變數
• ✅ 驗證設定
• ✅ 請求描述

範例

完整同步流程

# 設定環境變數
export POSTMAN_API_KEY=your_api_key
export POSTMAN_COLLECTION_ID=your_collection_id
export OPENAPI_PATH=./openapi.yaml

# 執行同步
postman-sync sync

# 查看變更報告
cat reports/sync-report.md

手動工作流程

# 1. 備份現有集合
postman-sync backup -c <collection-id>

# 2. 轉換 OpenAPI 規格
postman-sync convert -o ./openapi.yaml -d ./temp/new-collection.json

# 3. 合併集合
postman-sync merge -o ./backups/latest-backup.json -n ./temp/new-collection.json

# 4. 驗證合併結果
postman-sync validate -c ./temp/merged-collection.json

使用本地 npm scripts (開發模式)

如果您是在專案目錄下開發,也可以使用原有的 npm scripts:

# 完整同步流程
npm run sync
# 或
yarn sync

# 其他命令
npm run backup
npm run convert ./openapi.yaml
npm run validate

程式化使用

也可以在 Node.js 程式碼中使用:

const { syncCollection } = require("postman-openapi-sync");

async function main() {
  await syncCollection("./openapi.yaml", "collection-id");
}

main().catch(console.error);

取得 Postman API 金鑰

1. 登入 Postman
2. 進入 Settings > API Keys
3. 產生新的 API 金鑰
4. 複製並貼到 .env 檔案或使用 --api-key 參數

取得 Collection ID

在 Postman 中:

1. 開啟您的 collection
2. 點擊 collection 名稱旁的 "..." 選單
3. 選擇 "Share Collection"
4. 在 URL 中可以看到 collection ID (格式: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

專案結構

.
├── bin/
│   └── postman-sync.js       # CLI 入口
├── scripts/                  # 核心指令碼
│   ├── backup-collection.js
│   ├── convert-openapi.js
│   ├── merge-collections.js
│   ├── sync-collection.js
│   └── validate-collection.js
├── backups/                  # 備份檔案 (自動建立)
├── temp/                     # 暫存檔案 (自動建立)
├── reports/                  # 報告檔案 (自動建立)
├── package.json
└── README.md

授權

MIT License

作者

andy505050