雖然越來越多的組織將設計視為軟體開發生命週期以及 API 生命週期中的關鍵步驟，但很少有組織知道如何有效地大規模設計 API。當您在一個團隊中處理數量有限的服務時，設計更容易管理，並且依賴 PDF 風格指南或 Wiki 頁面可能足以讓所有人保持一致。但是，當設計流程需要跨越多個團隊以及數百甚至數千個不同的 API 時，會發生什麼情況？
建立真正可擴展的設計流程
我們推出了 SwaggerHub 來改變團隊協同設計和記錄 API 的方式。在過去的一年中，我們與數百位 SwaggerHub 使用者交談，以更好地了解他們如何能夠跨多個團隊以及越來越多的 API 來擴展其設計流程。一位使用者，CrowdFlower 的工程副總裁 Cameron Befus，解釋了他從開源 Swagger 設計工具轉移到 SwaggerHub 以進行更具擴展性的 API 設計的經驗
Crowdflower 一直使用 Swagger 來定義我們的 API 一段時間，而且由於 SwaggerHub，這個過程變得更加容易。擁有像 Swagger 和 SwaggerHub 這樣出色的工具，可以在設計新服務時促進協作，並使記錄和整合測試這些服務變得更加容易，這對我們的團隊有很大的幫助。
Bonotel 的資訊長 Scot Hastings 也分享了他最近為一個 API 專案啟動新設計流程的經驗
隨著專案的進展，我們意識到需要加快流程並使其更有效率。我們希望自動產生使用者介面，並在內部和外部團隊之間促進協作，而不會出現麻煩或溝通問題……透過使我們能夠更快地設計和開發 RESTful API，我們可以更快地將新服務和服務更新推向市場，” Hastings 說。“這使 SwaggerHub 成為我們軟體開發生命週期中的關鍵環節。”
像 CrowdFlower 和 Bonotel 這樣的組織能夠透過標準化使用 OpenAPI (Swagger) 進行 API 設計，並採用一種能夠無縫融入其 API 工作流程的工具，並使他們能夠在 SwaggerHub 中更有效地協作進行 API 設計，從而擴展其 API 設計。他們也代表了我們從成功擴展 API 設計流程的團隊中看到的一些關鍵原則。準備好擴展您的設計流程了嗎？以下是您需要採取的幾個重要步驟
1. 調整您的團隊
良好的 API 設計仰賴參與 API 開發生命週期的所有利害關係人之間的有效協調。如果您的團隊在設計需求上沒有達成一致，或者如果合適的人員無法獲得對設計變更的必要可見性，當您嘗試擴展到一小組 API 之外時，您將會遇到摩擦。組織嘗試使團隊成員在設計流程上保持一致的一種常見方式是透過協作工具，例如 Confluence 或 GitHub。但是，雖然這些工具在軟體開發生命週期中扮演著關鍵角色，但要針對管理 API 設計工作流程的特定用例進行配置可能會很複雜。SwaggerHub 的建立旨在協助團隊在整個 API 生命週期中保持一致。在 SwaggerHub 中，您可以建立組織並邀請團隊成員協作設計和記錄您的 API。組織的所有者可以根據團隊成員在設計流程中的參與情況，為他們分配角色並管理存取權限。進一步了解在 SwaggerHub 中協作。
2. 提高設計流程的能見度
與團隊在嘗試擴展 API 設計流程時可能面臨的協調挑戰類似，還有一個困難的任務，那就是提高團隊的能見度。我們經常看到，團隊會從開源 Swagger 工具（例如 Swagger Editor 和 Swagger UI）開始他們的 API 設計之旅。雖然這些工具提供了有效建模和視覺化 API 所需的功能，但它們並非為促進大型 API 團隊的協作需求而建構的。如果您使用 OpenAPI 來處理您的 API 設計，您會希望為整個團隊提供一個中心位置，以存取正在進行的不同服務設計工作。您還需要確保在發生變更時通知合適的人員，並且不要將能見度限制為分散的電子郵件、Slack 訊息和 GitHub 票證。
3. 減少依賴性
API 開發不僅可能是一個複雜的流程，對於相關團隊來說，它也可能是一個緩慢的流程。團隊之間的依賴性可能是想要超越設計以開始產生程式碼、起草文件和編寫測試案例的團隊減速的最大因素之一。團隊可以減少依賴性以實現更快開發的方法之一是透過 API「模擬」或虛擬化。SwaggerHub 中的 API 自動模擬整合會使用規格中定義的靜態回應來建立並維護您的 API 模擬。您可以在 SwaggerHub 中建立新 API 時自動建立模擬，也可以稍後隨時手動建立。此模擬有助於您在設計 API 時測試 API，也就是在開發人員實作 API 之前。此外，此整合可讓用戶端應用程式開發人員甚至在後端準備就緒之前就開始處理他們的部分。無需編寫任何程式碼，您就可以讓 API 使用者針對模擬開發用戶端，並保證模擬會以相容的、真實的酬載回應。更重要的是，您可以透過在模型定義中使用「範例」建構來直接調整 OAS 定義中的酬載。
4. 設定並強制執行設計要求
公司在 API 上的投資是一項長期事業。設計標準不僅能改進 API 的實作，還能決定 API 的更新方式或新 API 的開發方式。一旦設定了設計指南，就可以更容易地在此基礎上構建，並允許團隊開發 API，從而讓組織能夠擴展其設計和開發流程。由於設計定義了客戶端和服務的互動方式，因此設計上的差異會在服務開發階段導致混淆和額外負擔。這些不一致性只會不斷增加，其影響也會在 API 生命週期中放大。例如，資源中命名不一致的 API 可能在實作期間於控制器中使用不同的命名風格。SwaggerHub 透過我們的內建樣式驗證器來協助解決設計一致性的問題，該驗證器可檢查您的 API 定義是否符合特定的描述標準。例如，貴公司的指南可能要求所有屬性都必須指定範例。樣式驗證器可協助您自動執行此類檢查。建立樣式驗證器整合時，您需要指定要執行的檢查。
5. 提高設計中的重複使用性
我們經常從使用 Swagger 工具和 OAS 定義其 API 的 API 團隊聽到的一件事是，當在數百個 API 中定義多個端點時，設計過程可能非常繁瑣。當端點共享通用語法並具有相似的定義、路徑項目、參數和回應時，尤其如此。需要重複單獨定義每個端點會減慢設計過程，並導致 API 設計中的不一致。這就是 SwaggerHub 將網域概念引入設計過程的原因。網域是可以於多個 API 和其他網域之間共用的可重複使用元件。網域可以包含以下元件：定義、路徑項目、參數、回應。使用者可以建立和版本化網域，然後定義可以儲存在其中的可重複使用元件。使用者或 API 上的協作者可以從其他 API 或網域中參考這些元件。
6. 與您信任的工具整合
能夠從設計快速轉移到記錄、建置和部署 API，對於建立可擴展的 API 設計流程至關重要。如果當您開始超越 API 生命週期的初始階段時出現摩擦，那麼即使是最好的設計標準也無法幫助您擴展 API 設計。API 供應商嘗試解決這個問題的方法之一是在更針對 API 管理的工具之上建構額外的設計功能。雖然擁有一個多合一的解決方案很棒，但當您想要引入新工具時，也需要組織被鎖定在單一解決方案中，而沒有太多彈性。在 SwaggerHub 中，我們採取了不同的方法 — 建構一個世界級的 API 設計平台，供團隊作為其 API 設計流程的「單一事實來源」使用，然後無縫整合到您團隊信任的工具，以交付出色的 API，包括：Apigee、AWS、Microsost Azure 或 IBM API Connect 等 API 閘道、Bitbucket、GitHub 和 GitLab 等原始碼控制平台，以及用於功能測試的 SoapUI 等測試工具。深入瞭解 SwaggerHub API 生命週期整合。
擴展您的設計流程
無論您是已經有現行的設計流程，還是剛開始採用「設計優先」的 API 開發方法，SwaggerHub 都可以協助您的團隊標準化您的 API 設計、跨團隊協作，並使用 OpenAPI/Swagger 集中您的 API 設計工作流程。想要深入瞭解 SwaggerHub 如何協助您的團隊擴展設計流程嗎？請發送電子郵件至[email protected] 來安排示範，或與 SwaggerHub 團隊的成員聯繫。準備好開始了嗎？立即免費開始試用 SwaggerHub。