在我從事 ERP / HRM / BPM 套裝軟體的實務開發經驗中，雖然會提供 API 文件給第三方參考，但實際上大多數人更傾向使用更簡單的錄製方式。這種方法幾乎免除了閱讀文件的負擔，除非要深入了解參數，否則開發者通常不會再去查文件。

🔗 GitHub：https://github.com/jeff377/bee-library

1️⃣ 為什麼不用傳統 API 文件？

在 ERP / HRM / BPM 等企業系統裡，表單與流程動輒上千張，還包含套裝與客製化。
如果用傳統方式維護 Web API 文件，會遇到幾個問題：

• 文件更新速度落後程式，常出現 版本不一致
• API 參數龐雜，閱讀與理解 成本極高
• 不同模組文件風格不一，缺乏 一致性

2️⃣ 錄製的優勢

BeeNET 透過 Trace 機制，在使用者實際操作表單時，自動記錄 JSON-RPC 請求與回應，並輸出標準範本：

• ✅ 零維護成本：直接從程式執行過程錄製，不需手動撰寫文件
• ✅ 與版本一致：範本一定與當前執行版本相符
• ✅ 快速重播：可直接用 JSON 或 curl 在 Postman / CLI 測試
• ✅ 天然權限控管：錄製內容依登入帳號權限產生，不會超出可見範圍

開發人員只要開啟 TraceViewer，就能：

• 檢視所有攔截到的 ProgId.Action
• 點擊查看 JSON-RPC 範本 與 curl 測試指令
• 一鍵複製 curl 並匯入 Postman 直接測試

⚡ 無需再維護厚重的 API 文件，只要「操作一次 → 範本自動產出」。

3️⃣ 帳號與權限

就像一般 Web API，一樣需要專案帳號登入取得 AccessToken 才能進行錄製。

• 錄到的請求範例與該帳號的權限 一一對應
• 權限能做什麼，錄製就能捕捉到什麼
• 超出權限的功能或資料，自然不會被錄製

因此產出的範例不但能重播，還精準反映帳號可見的操作範圍。

4️⃣ 錄製成果示例

JSON-RPC 範本

{
  "jsonrpc": "2.0",
  "method": "Employee.Hello",
  "params": {
    "value": {
      "$type": "Custom.Define.HelloArgs, Custom.Define",
      "userName": "Jeff"
    }
  },
  "id": "f5ecd425-df49-4b8a-bb0e-2a7c017e67f6"
}

curl 範例

curl -X POST "https://localhost:7056/api" 
-H "Content-Type: application/json" 
-H "X-Api-Key: {YOUR_API_KEY}" 
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" 
--data '{
  "jsonrpc": "2.0",
  "method": "Employee.Hello",
  "params": {
    "value": {
      "$type": "Custom.Define.HelloArgs, Custom.Define",
      "userName": "Jeff"
    }
  },
  "id": "f5ecd425-df49-4b8a-bb0e-2a7c017e67f6"
}'

✅ 結語

• 「錄製」取代「文件」，大幅降低維護成本
• 範本與系統版本完全一致，不會出現文件落後問題
• 錄製內容自帶帳號權限限制，安全與真實性兼具
• 整合方只要拿到範本即可重播，不必再研究 API 文件

📘 HackMD 原文筆記：
👉 https://hackmd.io/@jeff377/webapi-recorder

📢 歡迎轉載，請註明出處
📬 歡迎追蹤我的技術筆記與實戰經驗分享
Facebook ｜ HackMD ｜ GitHub ｜ NuGet