我們用 SMART——Specific（具體）、Measurable（可衡量）、Achievable（可達成）、Relevant（具關聯）、Time-bound（有時限）——把每個故事拆成五天，作為每次動手造輪子前的五個檢查問題。

本篇是故事五「擔心客戶看不懂 OpenAPI 文件，我急到沒看到 Postman，先刻了一個範例 App」的 Achievable 篇：利用現有工具與最小變更，做得到嗎？

本篇定位：盤點現成工具能解決哪些導入問題，建立由低成本到高成本的支援順序。

當時發生了什麼

那封信之後不久的一次線上會議，客戶端的工程師分享畫面：他開著 Postman，左邊一排請求，上面的環境下拉選單寫著 staging 和 production。他一邊講一邊切換，網址和權杖就跟著換。

我當下兩種情緒交疊。一種是「原來他早就有這個」，另一種比較難堪：那兩週我沒有一次打開過 Postman，也沒查過「API 導入通常用什麼工具」。我腦中的解法從第一天就只有一個形狀——做一個 App——所有時間都用來把那個形狀做完，沒有一分鐘用來確認它對不對。

更難堪的是，他那份請求是從我們的 OpenAPI 檔匯入的，只是自己補了認證設定。我們手上早就有一份能變成可執行請求集合的資產，卻拿它當「文件不夠親切」的證據。

真正的問題在哪裡

第一個要拆的誤判是：覺得「文件不好用」，就去換一個渲染器，或乾脆自己寫畫面。但互動頁面只是規格的一種呈現，資產始終是規格本身。欄位沒描述、沒範例值、認證方式沒寫——規格爛的時候，換幾個渲染器都一樣爛，自己刻的畫面只是最貴的那一種爛法。

第二個問題是我們把支援想成是非題：要嘛丟一份文件給客戶自己看，要嘛做一套完整的產品給他用。中間有一整段連續的地帶，每一階都遠比寫一個 App 便宜，效果卻常常更好。跳過它們直接跳到最貴的一階，不是勇敢，是沒有盤點。

可以怎麼做

把支援方式排成一道階梯，從最便宜開始，每一階都先試過再往上爬。

第一階，修正 OpenAPI 契約與說明。 這是報酬率最高的一階，其他工具全都吃這份檔案。要檢查的是：端點有摘要、參數有描述與範例值、認證方式在 securitySchemes 裡宣告清楚、錯誤回應連同狀態碼定義。但「完整」不等於「可執行」，所以這一階要多做一件事：拿規格檢查工具跑一次，確認語法合法、必填欄位齊全、參照沒斷。規格檔連工具都讀不進去，後面每一階都會卡住。

第二階，提供 Swagger UI 或其他互動文件。 讓對方在瀏覽器裡直接送出請求，把「讀」變成「試」。這一階的實務門檻是跨來源資源共用（CORS，Cross-Origin Resource Sharing）：Try it out 是瀏覽器直接對 API 發請求，不是文件伺服器代發，所以文件與 API 不同源時，就得由 API 端補上 CORS 標頭；帶 Authorization 標頭又屬於非簡單請求，瀏覽器會先送一次 OPTIONS preflight。最省事的解法是讓它們同源：文件與 API 放在同一個 host 與 port，或擺在會補 CORS 標頭的反向代理後面，問題就不存在。

第三階，提供 Postman Collection 與環境設定範例。 多數團隊能直接從 OpenAPI 匯入產生 Collection，再補兩件文件做不到的事：把權杖或 API key 設成變數，附上測試與正式兩組環境範本，密鑰留白由客戶自己填。

認證是 OAuth 2.0 時要先分流程。client credentials 屬機器對機器、沒有使用者互動，換權杖的請求可以整包放進 Collection，完全自動化；authorization code（含 PKCE，Proof Key for Code Exchange）依規格必須經瀏覽器與 redirect URI 完成使用者同意，只能走工具的內嵌視窗或系統瀏覽器，無法在無頭環境自動完成。取得權杖之後，Postman 可以自動在背景更新，但它的排程執行與命令列執行不支援自動更新，沒先講清楚，客戶的 CI 管線就會卡在這裡。

第四階，提供 curl、SDK 或最小程式碼範例。 curl 的價值在於可複製、可貼進任何終端機、可以貼進工單當證據，是跨團隊談 API 問題的通用語。如果我們有維護各語言的 SDK，就附上一段從認證到取得資料的最小範例。這一階要克制：範例是示範呼叫方式，不是示範架構，越短越好。

第五階，提供工作坊、操作手冊與疑難排解。 把客戶問過的問題整理成一張錯誤碼對照：401 通常是權杖前綴漏掉或環境弄錯，403 是權限範圍不足，400 看回應指出的欄位名稱，404 多半是路徑或 ID 用錯，429 看重試間隔。這一階解的是知識問題，而且能重複使用：每來一個新客戶，成本趨近於零。

第六階，確認有正式產品需求後，再開發應用程式。 圖形介面不是錯的選項。判準不在使用者長什麼樣子，在立項條件湊不湊得齊：有明確的需求來源（誰、為了哪一段流程提出）、有範圍、有預算與商業條件、有維護與資安的負責人、有值班安排。缺一件就代表還不到這一階：不是不能做，是還沒有人決定要做。我們當初那個 App，一件也沒有。

爬階梯有兩個原則。一是往上爬要有理由：說得出前一階為什麼不夠，理由要來自客戶實際遇到的狀況。二是每一階都留下客戶帶得走的東西——一份可匯入的規格檔、一組請求範例、一份環境設定範本、一頁錯誤碼對照，全是他關掉會議之後還能用的資產，也呼應那張把客戶放在中央的驗收表。

回頭看那兩週，我們真正需要的可能只是第一階加第三階。攤成工作項就是：規格裡補上認證宣告、改掉兩處欄位說明、產一份 Collection、附一組環境範本。沒有一項需要挑前端框架。

今天學到的事

在開發另一套軟體以前，先確認問題是否早已能由文件、工具與可執行範例解決。這句話像常識，在現場卻很難執行：我們並非不知道有這些工具，而是動手的衝動比查資料強得多——寫程式有立即的進度感，盤點工具只會讓人覺得什麼都沒做。

階梯的存在本身就有價值，即使最後真的爬到第六階——那時我們帶著前五階的證據往上爬，憑的不再是一句「客戶說不會用」。

但那個已經做出來的 App 呢？它不會因為我們事後畫了一張階梯就消失。東西一旦交出去，就會長出我們沒預期的關係。那些關係會長成什麼樣子？