雖然越來越多組織將設計視為軟體開發生命週期以及 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 工具開始他們的 API 設計之旅，例如 Swagger Editor 和 Swagger UI。雖然這些工具提供了有效建模和視覺化 API 所需的功能，但它們並非旨在促進大型 API 團隊的協作需求。
如果您使用 OpenAPI 來處理 API 設計，您會希望為整個團隊提供一個中心位置，以存取正在完成的設計不同服務的工作。您還需要確保在發生變更時通知相關人員，並且不會將可見性限制在不同的電子郵件、Slack 訊息和 GitHub 票證中。
3. 減少依賴性
API 開發不僅可能是一個複雜的過程，對於參與的團隊來說也可能是一個緩慢的過程。團隊之間的依賴性可能是減慢想要從設計轉向開始產生程式碼、起草文件和編寫測試案例的團隊速度的最大因素之一。團隊能夠減少依賴性以加快開發的一種方法是透過 API「模擬」或虛擬化。
SwaggerHub 中的 API 自動模擬整合使用您規格中定義的靜態回應來建立並維護 API 的模擬。您可以在 SwaggerHub 中建立新 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、Microsoft Azure 或 IBM API Connect 等 API 閘道、Bitbucket、GitHub 和 GitLab 等原始碼控制平台，以及 SoapUI 等用於功能測試的測試工具。
了解更多關於 SwaggerHub API 生命周期整合的資訊。
擴展您的設計流程
無論您是已經有既定的設計流程，還是剛開始使用 API 開發的「設計優先」方法，SwaggerHub 都可以協助您的團隊標準化 API 設計、跨團隊協作，並使用 OpenAPI/Swagger 將 API 設計工作流程集中化。
免費試用 SwaggerHub！了解為什麼超過 70,000 名 API 開發人員、設計師、架構師、資訊長等都信任 SwaggerHub 來幫助擴展他們的 API 設計流程。
立即免費開始試用 SwaggerHub.
有問題或想了解更多關於如何改進 API 設計流程的資訊嗎？請聯絡 SwaggerHub 團隊：[email protected]