DocDriven

DocDriven 是什麼

DocDriven是一個面向前端、後端、產品及設計團隊的視覺化API設計平台，由丹麥公司Nordicode ApS所運營。它將接口設計、文件、Mock服務、審核流程、變更記錄以及AI代碼生成等功能整合在相同的共享工作區中。

此處的「設計」指的是端點、請求、回應以及資料架構的設計，而非圖片、標誌或介面素材的製作。這種做法適用於在正式開發之前對齊 API 條款，從而減少前端與後端的等待時間，並避免出現破壞性的變更。

主要功能概覽

可視化 API 設計

團隊可以在介面中建立端點、方法、參數、請求體、回應以及資料模型，這樣就能減少在直接編輯 YAML 時出現的結構錯誤。自動補全功能以及根據既有屬性所給出的建議，有助於保持名稱與 Schema 的一致性。

• 後端開發者可在編碼前確定資源、錯誤模型和版本策略。
• 前端開發者可提前確認頁面所需欄位和互動流程。
• 產品經理可查看接口進度、負責人及未解決的問題。
• UI設計師可核對界面需要的數據是否已在一併的契約中體現。
• 外部訪客可參與特定專案評審，而不必擁有整個工作區的權限。

可視化編輯無法取代 API 管理。團隊仍需定義認證、授權、冪等性、分頁、錯誤碼、速率限制及相容性規則。

OpenAPI 導入與統一文件

新專案既可以從空白狀態開始，也可以導入現有的 OpenAPI 標準。如此一來，分散在內部及外部的介面就能被整合到同一個工作區中，成為前端、後端以及相關利益方都可以參考的契約。

1. 建立工作區和專案，或選擇匯入現有的規範。
2. 檢查端點、Schema、範例和安全定義是否完整導入。
3. 補充業務說明、錯誤回應和邊界條件。
4. 邀請成員或外部訪客評審，並分配待處理問題。
5. 發布確認後的 API 版本，建立變更基線。
6. 讓前端連接 Mock Server，後端按契約實現。

導入成功並不代表規範語義完全正確。循環引用、自訂擴展、安全方案以及複雜的多態模型都需要另行測試。

Mock Server 如何使用

DocDriven 可根據 API 設計創建即時雲端 Mock Server，讓調用方在真實後端尚未完成時測試請求和回應。前端、行動端和自動化測試可以圍繞同一契約並行工作。

• 為回應定義具有代表性的成功、驗證失敗、未授權和伺服器錯誤範例。
• 不要把生產密鑰、真實個人資訊或客戶數據寫入範例。
• 確認 Mock 回應的狀態碼、標頭和延遲是否覆蓋用戶端邏輯。
• 後端上線後用契約測試比較實際實現與設計。

Mock Server 只是模擬服務，無法證明真實後端的性能、安全、事務和資料一致性已經滿足要求。

實時協作與責任管理

團隊成員可以查看計劃的變更、對接口方案提出意見、報告問題，並指定負責人。而項目訪客則只能存取被邀請的項目，無法查看其他項目或管理區的設定。

評審記錄應說明決策原因、相容性影響及遷移計劃，而非僅標示已完成。涉及公共或合作夥伴的 API 時，還應建立正式的審批與發布流程。

Changelog 與 Baseline

基線會擷取某個時間點的 API 狀態，並將後續的設計與之比較。差異會依新增、刪除和修改的端點或 Schema 來分類，這有助於團隊及早發現可能破壞用戶端功能的變更。

• 在穩定發布前建立明確基線。
• 檢查字段刪除、類型修改、必填狀態和請求結構變化。
• 為破壞性變更制定新版本和遷移期限。
• 在 Changelog 中補充業務背景、發布日期和升級動作。
• 將差異評審納入 Pull Request 或發布流程。

自動差異能發現結構變化，但未必理解業務語義。欄位含義、預設值或權限變化，即使 Schema 不變，也可能影響呼叫方。

AI Code Assistant

Code Assistant 會參考 GitHub 儲存庫中的範例檔案和團隊設定，為 DocDriven 中的端點或 Schema 生成程式碼。它的目標是依照既有的規範來產生樣板實作，而非自行完成所有的業務邏輯。

配置檔案要求

倉庫的根目錄中需要有 docdriven.config.json 檔案，而每個模板則包含名稱、範例檔案、輸出目錄以及目標類型。目標可以是 Endpoints 或 Schemas，而範例檔案則用來示範所產生代碼的結構與風格。

輸出方式

• 創建 Pull Request，供開發者評審後合併。
• 提交到當前選擇的分支。
• 提交到其他分支或其他已授權倉庫。
• 在日誌頁查看生成過程、失敗和完成狀態。

優先選擇 Pull Request，並讓測試、靜態分析以及人工審查共同把關。所生成的代碼可能包含錯誤、過度的權限、不安全的輸入處理方式，或是與業務規則不相符的實作。

GitHub 連接與安全

要使用 Code Assistant，必須先取得 GitHub 的授權，如此 DocDriven 才能存取儲存庫、讀取程式碼範例，並提交生成的內容。此授權範圍會直接影響到私人程式碼以及供應鏈的安全性。

• 只授權確實需要的組織和倉庫。
• 使用專用分支、受保護主分支和強制 Pull Request 審查。
• 不要在範例檔案、設定或日誌中放置金鑰。
• 定期檢查 GitHub 應用權限並撤銷不再使用的連線。
• 對生成依賴運行漏洞、許可證和惡意包檢查。
• 離職、專案結束或試用期結束時，立即收回訪問權。

價格與套餐

試用時無需信用卡，但試用期結束後必須選擇付費方案，否則帳戶將被暫停使用，直到訂閱服務或關閉帳戶為止。Team方案的價格可能會受到月付、年付方式、稅金以及地區差異的影響；至少需要三個席位時，其團隊成本才會高於單個席位的價格。

升級會按當前週期進行比例計費，降級則從下一計費週期開始生效。公開頁面未提供清晰的退款規則，付款前應確認續費、取消、未使用週期以及稅費的處理方式。

隱私與資料處理

隱私政策中所列的運營主體為 Nordicode ApS，更新時間為 2023 年 12 月。該平台會處理用戶的姓名、電子郵件、帳號、付款及使用相關資訊，而支付數據則由 Stripe 負責處理。服務條款中規定，系統是託管在德國的。

• 服務可能使用帳戶資訊完成認證、交付、溝通、安全與改進。
• 用戶可依據適用法律要求存取、更新或刪除個人資訊。
• 平台聲明採用組織與技術措施，但不保證所有風險都能消除。
• 服務未依 HIPAA、FISMA 等行業專項法規設計，受監管團隊應謹慎。
• GitHub 儲存庫、API 設計及所產生的程式碼可能包含商業機密，應先完成供應商審查。

隱私頁面並未充分說明 AI Code Assistant 所使用的模型供應商、代碼的保存期限以及訓練用途。在接入私有倉庫之前，應先向銷售方確認資料處理協議、子處理方、備份與刪除規定，以及模型資料政策。

條款、版權與商用限制

條款允許在符合規定的情況下，將服務用於內部業務目的，並保留平台代碼、資料庫、設計及品牌的權利。該平台並非開源代碼庫，支付訂閱費用並不代表可以複製或轉售其服務。

• 用戶應確保上傳的 API、代碼和內容擁有必要權利。
• 直接提交的建議可能按條款轉讓給運營方，發送機密創意前應評估。
• 公開貢獻可能授予範圍廣泛的使用許可，不應將私有設計放入公共區域。
• 服務可能發生變更、中斷或終止，團隊需要導出關鍵規範並自行備份。
• 條款適用丹麥法律，跨地區企業應評估合約與資料責任。

平台、API 與開源狀態

適合用戶與場景

• 後端團隊：在實作前統一資源、Schema、錯誤和版本規則。
• 前端與行動團隊：用 Mock Server 事先開發並驗證介面。
• 產品經理：追蹤接口計劃、評審問題與負責人。
• 平台工程團隊：維護多個內部和外部 API 的一致性。
• 技術負責人：審查 Baseline 差異並控制破壞性變更。
• 使用 GitHub 的團隊：依照現有的程式碼風格，產生可供審查的範本實作。

優勢與能力邊界

主要優勢

• 將 API 設計、Mock、協作、變更記錄和代碼生成放在同一工作流。
• 可視化編輯降低非後端角色參與介面評審的門檻。
• Baseline 讓端點與 Schema 的差異更直觀。
• Code Assistant 以倉庫範例和配置約束輸出風格。
• 30 天全功能試用適合真實團隊驗證。

主要限制

• AI 生成的代碼仍需審核、測試和安全檢查。
• 至少三席的 Team 計劃不適合只需一個帳號的個人。
• Mock Server 不能替代真實後端測試。
• 未公開模型供應商、代碼處理細節、平台 API 和源碼。
• 服務並非為特定高監管框架量身設計。
• 文件仍標註為持續完善，部分邊界可能需要向支援確認。

常見問題

DocDriven 是界面設計工具嗎？

不是。它設計的是 API 端點、請求、回應和資料模型，並幫助前後端圍繞介面契約協作。

試用期需要信用卡嗎？

不需要。30天試用期可享受單一工作區及所有功能，期滿後若未付款，帳戶將被暫停使用。

Team 計劃最低需要幾個人？

當前頁面規定至少 3 名付費用戶，另可邀請無限訪客。實際總價應在結算頁確認。

能導入現有 OpenAPI 嗎？

可以從現有的 OpenAPI 標準來建立專案。導入之後，仍需檢查自訂擴充功能、安全定義以及複雜模型。

Mock Server 可以當生產後端嗎？

不可以。它用於模擬設計、前端並行開發和契約測試，不具備生產業務邏輯與數據保證。

AI 會直接改主分支嗎？

輸出方式可設定為 Pull Request、目前的分支，或是其他分支與儲存庫之間的連結。生產團隊應使用受保護的分支，並實施強制審核機制。

生成的代碼會遵循團隊規範嗎？

Code Assistant會參考設定檔和範例代碼，但仍可能偏離規則。必須進行格式化、測試以及人工審核。

DocDriven 是開源的嗎？

不是可確認的開源產品。支援 OpenAPI 與 GitHub 整合並不代表平台源代碼是開放的。

有公開平台 API 嗎？

目前尚未發現適用於一般開發者的 DocDriven API 或 SDK。若需要自動化功能，應先向產品團隊確認。

適合醫療或高度監管數據嗎？

條款明確服務並非為部分行業專項法規設計。涉及受監管接口或代碼時，應完成合規和合同審查後再接入。

總結

DocDriven 適合那些希望在編碼之前就建立共用的 API 條款，並透過模擬、差異追蹤及 AI 樣本代碼來降低協作成本的團隊。在購買之前，應特別檢視 GitHub 的權限設定、模型資料政策、最低訂閱數量以及資料備份流程。