API 開發在過去幾年中蓬勃發展，這已不是什麼秘密。在我們的《2019 年 API 產業現狀報告》中，我們發現有三分之二的組織在過去五年內才開始開發 API。隨著組織擴展其 API 實務，他們開始採用工具來依照 OpenAPI 規格（以前稱為 Swagger）設計 API。
SwaggerHub 是一個協作平台，可讓團隊組織和管理其 REST API，同時擴展和標準化設計實務。
我們經常被剛開始使用該平台的團隊問到：
「我的團隊應該採用哪些最佳實務，才能充分利用 SwaggerHub 來進行 API 設計和文件編寫？」
以下是 5 個能實現一流 API 設計的頂級 SwaggerHub 實務
1. 在您的組織中定義並強制執行 API 標準化
在我們的《2019 年 API 現狀報告》中，團隊開發和使用 API 的首要挑戰是「缺乏標準化」。如果您的團隊正在建構和依賴的 API 設計不一致，它們可能難以互動和維護。
在 SwaggerHub 中，可以輕鬆自動檢查樣式指南的相容性。您只需選取要套用至組織的樣式規則，您就能立即看到哪些 API 需要更新。
當您的團隊設計新的 API 時，這些樣式規則將會顯示在編輯器中，以便每個新的 API 都以標準化、一致的方式建構。
如果您的團隊目前正在進行人工審查以確保設計一致性，這種樣式檢查自動化可以節省大量時間並減少錯誤。這些審查可以將重點放在分享知識和最佳實務，而不是標記樣式錯誤。
2. 使用組織、專案和團隊來管理您的 API 定義和權限
根據您的公司，您可能會在數百個不同的 API 上工作和與之合作。如果您的組織只依賴 GitHub 和 Bitbucket 等儲存庫，就難以清楚了解誰擁有什麼。透過在 SwaggerHub 中管理您的 API，您可以為所有 API 和文件建立集中式事實來源。
SwaggerHub 中的組織提供了一種簡單的方法來管理群組擁有的 API 定義，以及誰可以存取它們的權限。首先邀請同事成為成員並匯入您現有的 API。接下來，將成員分組為團隊、將 API 分組為專案，並開始使用 SwaggerHub 編輯器設計新的 API。
在內部，SmartBear 有一個公司範圍的開發組織，然後根據他們使用的每個工具來組織團隊和專案。例如，LoadNinja 的工程團隊（SmartBear 的一個 UI 效能測試平台）使用 SwaggerHub 來託管其內部和外部 API 文件。SwaggerHub 作為開發人員協作並了解 LoadNinja 各種內部服務的中心事實來源。
3. 為常見 API 元件建立網域
在我們的《2019 年 API 現狀報告》中，75% 的受訪者表示，他們認為微服務架構將在未來兩年內推動 API 採用量的最大成長，而在 2016 年，只有 20% 的人持這種觀點。如果您的團隊正在擴展 API 開發，您的工作中很可能會有常見的元件，例如參數、回應和資料模型。
SwaggerHub 網域讓您可以遵循「不要重複自己 (DRY)」原則，而不是為每個 API 寫出 404 錯誤，透過建立這些常見元件的程式庫。只需在您的錯誤網域中參考 404 錯誤架構，然後繼續設計。
這種可重複使用性意味著您的團隊需要較少的人工工作，因此降低了專案中的風險。它也意味著當變更發生且標準化元素發展時，只需更新單一位置。
我們稍早提到設計標準化是 2019 年團隊面臨的首要挑戰。網域讓您的組織可以使用標準定義。如果「客戶」或「員工」的定義在您的業務中保持一致，最終使用者在與您的 API 互動時會更容易知道要期待什麼。
4. 使用自動模擬提前驗證設計
您的團隊越早測試設計，就越容易反覆運算並修正問題。當設計人員使用 SwaggerHub 編輯器來撰寫和視覺化 Swagger 定義時，他們會開始透過內建的自動模擬（由與另一個名為 VirtServer 的 SmartBear 工具整合提供）來提前驗證行為。
這個 VirtServer 整合會自動建立並維護在 SwaggerHub 中定義的 API 的半靜態模擬。每次您儲存 API 時都會更新這個模擬，這表示您不再需要特地建立模擬服務。使用 VirtServer 產生的預覽，透過幾個按一下動作，即可與您的團隊反覆運算設計。
自動模擬為設計人員提供關於他們工作的立即回饋，但也會影響您軟體團隊其餘成員的工作方式。有了模擬，開發人員就可以並行開發用戶端應用程式，而無需等待後端 API 工作完成。
5. 將 SwaggerHub 納入您的 CI/CD 管道策略
許多團隊現在都希望透過整合整個軟體開發生命週期中的不同工具來建構 CI/CD 管道。
SwaggerHub 與 AWS、Microsoft Azure、IBM API Connect 和 Apigee 等 API 管理平台具有原生整合，因此很容易將其納入您的交付管道。
當 SwaggerHub 作為組織 REST API 的事實來源時，它最有用。透過將您的 API 定義與 GitHub、Bitbucket 和 GitLab 等原始碼控制儲存庫同步，您可以確保跨平台和組織的文件和程式碼的版本控制一致性。團隊甚至可以將 SDK 和程式碼範本推送至這些儲存庫系統，減少建構新服務的許多前期工作，並讓開發人員首先專注於邏輯和功能。
您也可以設定 SwaggerHub Webhook 來建立自訂工作流程。例如，CrossBrowserTesting.com（SmartBear 的一個網站測試平台）背後的團隊使用 SwaggerHub 來定義其 API 並在一個地方管理文件。使用 webhook，他們已將 SwaggerHub 與範本工具連線，該工具會即時取得 JSON 定義檔並以統一的方式顯示它。
開始使用
如果您的團隊已在使用 SwaggerHub，如果您對這些最佳實務有任何疑問，請隨時聯絡我們。如果您尚未使用 SwaggerHub，您可以建立免費帳戶並匯入您現有的 API 來開始使用。