API 設計圖如何進入 CI/CD？打造 Design-First 與 GitOps 的完美同步工作流
最遙遠的距離 在推行 Design-First (設計優先) 的過程中，很多團隊會遇到一個尷尬的斷層： 架構師在 Swagger 把規格寫得很完美，按下存檔。 然後呢？ 然後後端工程師要打開 Swagger，手動點擊「Export YAML」，下載到本機，解壓縮，把檔案複製到專案資料夾，覆蓋舊檔，然後再 git commit。 只要有一個步驟忘記做，或是複製錯版本，程式碼跟設計圖就會開始脫節。 這就是為什麼很多工程師討厭 Design-First：「因為很麻煩啊！我直接改 Code 比較快。」 這樣的理解或許也沒錯，但那是因為你還沒遇到 SmartBear Swagger (SwaggerHub)！ 今天我們要介紹如何利用 Swagger (SwaggerHub) 的 Git Sync 與 CI/CD 整合，把這段「最遙遠的距離」變成「自動化的高速公路」。 什麼是 Git Sync？讓設計圖自動歸位 SmartBear Swagger (SwaggerHub) 內建了與 GitHub、GitLab、Bitbucket 還有 Azure DevOps 的原生整合功能。 一旦設定好 Git Sync，神奇的事情就發生了： 當架構師在 Swagger (SwaggerHub) 上按下 “Save” 的那一瞬間，系統會自動在背後觸發一個 Commit，將最新的 OpenAPI […]
別讓每個微服務都重新定義「User」！利用 Domain 模組化設計達成真正的標準化
微服務的「碎片化」惡夢 微服務架構 (Microservices) 的初衷是解耦 (Decoupling)，讓每個服務可以獨立開發、獨立部署。這聽起來很棒，但在 API 設計上，這往往演變成一場災難。 試想一下，你們公司有「訂單服務」、「會員服務」和「物流服務」。這三個服務都需要用到 「使用者資料 (User Profile)」。 結果發生了什麼事？ Team A (訂單) 定義的 User 有 user_id 和 email。 Team B (會員) 定義的 User 有 uid 和 e-mail (多了一個連字號)。 Team C (物流) 定義的 User 有 id 和 contact_email。 雖然都在講同一個「人」，但欄位名稱完全不同。這導致前端團隊在串接時，必須寫三套不同的邏輯來解析資料。這不叫「獨立」，而是「疊床架屋」（Reinventing the wheel）且製造混亂。 今天我們要聊聊，如何利用 SmartBear Swagger (SwaggerHub) 的 Domains (領域) 功能，來終結這種各自為政的亂象。 什麼是 API Domains (領域模型)？ 在寫程式時，我們都知道要把共用的函式抽出來變成 […]
REST API 設計規範：如何讓團隊不再為 camelCase 還是 snake_case 吵架？自動化 Style Guide 才是解藥
開發會議上的「不停內耗」 身為技術主管或資深工程師，您一定經歷過這種場景： 在 Code Review 會議上，兩個工程師爭得面紅耳赤。 A 說：「API 欄位應該要用駝峰式命名 (camelCase)，像 userId！」 B 說：「不對！資料庫欄位是底線式 (snake_case)，API 應該要對應，用 user_id！」 C 默默舉手：「那個…你們有沒有發現他的 Error Code 回傳是 200 OK 但是內容寫 ‘Failed’？」 這些關於「風格」與「規範」的爭論，往往消耗了團隊大量的時間，卻對業務邏輯沒有直接幫助。但如果不統一，當這些 API 被前端或合作夥伴串接時，災難就發生了——沒有人知道這家公司的 API 到底該怎麼用。 今天我們要聊的，就是如何用「自動化工具」來終結這場不必要的內戰。 什麼是 API Style Guide (風格指南)？ 在程式碼的世界裡，我們有 ESLint 來檢查 JavaScript 語法；同樣的，在 API 設計的世界裡（OpenAPI/Swagger），我們也需要一套 API Style Guide，也就是 API 規範的風格指南。 它是一組定義明確的規則，例如： 命名慣例：所有的 URL Path 必須是小寫且用連字號分隔 (kebab-case)。 安全性：所有的 […]
API設計 – 最佳實踐
好的 API 設計是許多團隊在完善其 API 策略時經常討論的主題。如果 API設計 的好，帶來的好處包括：改善開發者體驗、更快的文件編寫速度，以及 API 的更高採用率。但是，究竟什麼構成了一個好的 API設計 呢？在這篇文章中，我將詳細介紹設計 RESTful API 的一些最佳實踐。 好的 API設計 特色 一般來說，一個有效的 API 設計應具有以下特色： 1. 易於閱讀和使用：設計良好的 API 會很容易使用，開發者在經常使用後，能夠快速記住那些 Resource 和相關的 Operation。2. 不容易被誤用：實現並整合一個設計良好的 API 會是一個簡單直接的過程，而且比較不容易寫出錯誤的程式碼。它會提供有用的回饋資訊，而且不會對 API 使用者強加過於嚴格的規範。3. 完整且精簡：最後，一個完整的 API 能讓開發者基於你公開的數據，打造功能齊全的應用程式。通常，完整性是隨著時間逐漸實現的，大多數 API 設計師和開發者會在現有 API 的基礎上逐步增強。這是每個擁有 API 的工程師或公司應該努力追求的理想目標。 為了說明這些概念，我會用一個照片分享APP為例。這個APP允許使用者上傳照片，並標記拍攝這些照片的位置和描述其情感的標籤（hashtags）。 Collections、Resource 及它們的 URL 了解 Resource (資源) 和 Collections (集合) Resource 是 REST 概念中的核心元素。簡單來說，Resource […]
API 設計優先（Design-First）與開發優先（Code-First）：哪個更適合我？
以下將深入探討 API 設計優先（design-first）和開發優先（code-first）的文章，並提供了實際案例、ROI 計算，以及如何使用 SwaggerHub 幫助團隊簡化並輕鬆上手設計優先的流程。 設計優先 vs 開發優先：基本概念 在當今數位轉型的時代，API（應用程式介面）成為了企業技術基礎的核心。無論是內部系統整合，還是與第三方應用程式交互，API 扮演著至關重要的角色。然而，在建立 API 的過程中，企業面臨著一個關鍵選擇：應該選擇設計優先（Design-First）還是開發優先（Code-First）的方法？（有些人則稱 Code-First 為功能優先）這兩種方法各有其適用的場景和挑戰，選擇適合自己企業與團隊的方法可以大幅提高開發效率、降低成本，並提升 API 的品質。 設計優先（Design-First） vs 開發優先（Code-First） 設計優先（Design-First） 是指在撰寫任何程式碼之前，先行設計並定義 API 的結構，通常是基於 OpenAPI 規範。這種方法強調 API 的規範和文件在一開始就清楚定義，並讓前端和後端開發團隊能同步進行開發。 開發優先（Code-First） 則是先撰寫程式碼，然後再根據實現的內容生成或編寫 API 文件。這種方法通常適用於較小、開發週期較短的專案，因為它允許快速的迭代和實現。 下圖概略描述了兩個流程的差異： 適合開發優先（Code-First）的專案類型與時間範圍 開發優先方法更適合以下類型的專案/團隊： 舉例來說，當某個團隊開發一個內部工具 API，其需求簡單且團隊人數較少，使用開發優先可以迅速推出可用的功能。然而，當專案的規模超過 6 個月、涉及多個開發團隊或需要與外部應用程式整合時，開發優先容易因為文件不一致、需求變更和溝通不暢而造成問題。 設計優先可以解決的問題 1. 需求變更與一致性 設計優先方法能在專案初期將 API 的需求和行為清楚定義，這樣即使後續有需求變更，也能根據設計的規範進行調整，避免因缺乏清晰文件而引發的返工或混亂。由於規範在一開始就確立，API 的行為和結構能夠保持一致，降低了後期出現問題的機率，尤其在涉及多次迭代或長期維護的專案中，這種一致性至關重要。 2. 團隊合作與溝通效率 設計優先方法能讓所有相關團隊（前端、後端、測試、產品經理）在 API 開發前就達成一致，明確 API 的行為與邊界。這減少了因溝通不良而產生的錯誤，特別是在涉及多個團隊或分佈式開發的情況下，統一的 API 設計規範能顯著提高合作效率。更重要的是，前端和後端可以同步進行開發，前端團隊可以根據設計好的 […]