# 用錄製自動產生 Web API 請求範本


> 在我從事 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 文件

---
**📢 歡迎轉載，請註明出處**
**📬 歡迎追蹤我的技術筆記與實戰經驗分享**
[Facebook](https://www.facebook.com/profile.php?id=61574839666569) ｜ [HackMD](https://hackmd.io/@jeff377) ｜ [GitHub](https://github.com/jeff377) ｜ [NuGet](https://www.nuget.org/profiles/jeff377)