將 Amazon API Gateway 上的 API 快速文件化
程式碼優先或設計優先，選最適合您的方法
最困難的爭論之一是在程式碼優先的 API 方法還是設計優先之間做出決定。在理想的世界中，我們將以最快的速度交付 API，並以最少的維護。為了維持適當的 API 消耗，全世界都將 Amazon 的 API Gateway 視為大規模建立、部署和管理 API 的資源編排。
使用者在使用任何 API 網關時面臨的最大挑戰之一是整個 API 體驗缺乏一致性和標準化。這在大型組織中很常見，其中有多個團隊負責維護複雜的 API 生態系統。結果是不合邏輯且不可預測的 API 體驗進一步影響 API 的使用和採用。
為了有效管理廣泛的 API 網路，我們需要開始記錄 API，並正確記錄它。一些 API 設計工具，例如 SmartBear 的 SwaggerHub，允許我們將 API 匯入到工具中並自動解析程式碼庫以建立文件。SwaggerHub 具有更多功能，使開發人員能夠設計、建置和記錄 API。借助 OpenAPI 規範（以前稱為 Swagger），使用者可以建立自訂規則來強制所有 API 設定為相同的標準。
在程式碼優先和設計優先之間做出決定並不總是那麼容易。目標應該是以最高效率記錄 API 並使其標準化。有些項目需要程式碼優先，有些項目需要設計優先。程式碼優先非常適合快速入門並從頭開始建立應用程式。由於文件是從程式碼產生的，因此它是最新的。但文件中可能缺乏內容或上下文。由於它以程式碼為中心，因此可能無法提供足夠的細節或 100% 正確。設計優先以在 API 文件中提供更好的清晰度和指導而聞名，從而改善 API 的協作和採用。儘管在實作之前為 API 編寫文件的最初努力並不總是值得的，但文件和功能之間可能會出現脫節，稱為 API 漂移。
好處是，使用其中一種與另一種沒有限制。如果做得正確，我們希望所有人都能獲得一致的 API 體驗。託管在最常用的網關之上，使我們能夠即時查看最終用戶的 API 體驗，並在必要時修改體驗。
使用 Amazon API Gateway 和 SwaggerHub 實作程式碼優先
現在是時候記錄 API 了。我們的 API 已經託管在 API Gateway 上。首先要去到我們希望落實標準化或記錄的 API，並發布 API 文件（必須部署 API 才能發布文件）。
圖 1 – 將 API 文件從 Amazon API Gateway 發佈到 Swagger YAML
現在讓我們將 API 匯入到 SwaggerHub。匯入 API 後，它將自動執行標準 Open API 規範驗證，以確保 API 正確，並啟用任何其他自訂規則。
圖 2 – 將 YAML 導入 SwaggerHub
SwaggerHub 具有許多其他優點，可與任何 API Gateway 搭配使用。SwaggerHub Domains 提供了一個集中位置來管理 API 的常見元件，例如 Schema、安全定義、Response 等。透過使用 Domain，API 開發人員可以一次建立和管理這些元件，然後在多個 API 中重複使用它們，從而減少重複工作、確保一致的設計、減少錯誤並實現快速的 API 開發。
圖 3 – 使用 SwaggerHub 改進 API 文件
Amazon API Gateway 和 SwaggerHub 都具有指令列介面，可透過兩步驟管道協助自動化整合。必要條件是從 AWS 和 SwaggerHub 下載並設定必要的指令列介面。在 Pipeline 的第一步中，我們使用 AWS CLI 從 API Gateway 匯出 REST API。接下來，我們使用 SwaggerHub CLI 在 SwaggerHub 中建立 API。一旦 API 進入 SwaggerHub，API 驗證和自訂指南就會自動解析 API 規範，以確保一致的 API 體驗。
圖 4 – 使用 SwaggerHub 和 API Gateway CLI 透過自動化進行整合
使用 Amazon API Gateway 和 SwaggerHub 實現設計優先
實作設計優先的 API 方法是為了幫助提高短期速度和長期一致性。設計優先所承載的一致性和標準是大多數新 API 如此建立的主要原因。API 是使用 API 描述語言建立的，以幫助就 API 的行為方式建立契約。
首先，與利害關係人討論 API，以確定 API 應建立的關鍵服務和業務功能。然後，我們設計 Open API 規範中的 API 合約。建立初始 API 規格後，我們就可以連接到 API Gateway 。API 本身處於什麼狀態並不重要；當我們改進 SwaggerHub 中的 API 時，API 的變更和改進可以自動推送到 Gateway。這產生了平行測試和開發的能力，並且更符合 Shift-Left（左移）。
SwaggerHub 有兩個整合可以幫助我們立即自動將 API 推送到 Amazon API Gateway。透過設定 SwaggerHub API Gateway Integration，以便每次您在 SwaggerHub 中儲存 API 時，Amazon API Gateway 都會透過引用模擬中的虛擬化 SwaggerHub API 自動呈現這個變更。
圖 5 – 部署後的 SwaggerHub API 網關整合
另一個 SwaggerHub Amazon API Gateway 整合是 SwaggerHub Gateway Lambda Sync。差別在於您使用的 Back-end 類型。如果您有現有的 API 伺服器並且希望透過 Gateway 進行 Proxy 或保護，那麼 SwaggerHub API Gateway Integration 是正確的選擇。SwaggerHub Gateway Lambda Sync 使用 Lambda 函數作為 Back-end。在 SwaggerHub 中設定整合後，API 將自動部署到 Amazon API Gateway。
圖 6 – 部署的 SwaggerHub API Gateway Lambda Sync
產生 Lambda 函數後，我們就可以將 API 提升到一個新的水平。為此，我們在與 Lambda 函數關聯的 API 資源之上插入 Python 或 Nodejs 的 run-time 引擎，將 API 轉換為功能齊全的應用程式。
圖 7 – 同步到 SwaggerHub 的 Lambda 函數
結論
程式碼優先或設計優先沒有絕對的對錯，兩種方法都有其優點和錯置的可能性。API 文件化的最佳解決方案是正確地進行記錄。無論團隊喜歡先建立應用程式程式碼庫還是先開發文件，如果我們在任何階段正確記錄，就不會出現不一致的情況。現在，隨著規模的擴大，我們可以使用 Amazon API Gateway 和 SwaggerHub 有效管理廣泛的 API 網路。結合這兩個工具將有助於為 API 使用者提供豐富的 API、搭配有效的範例、提供最低的延遲，並具有靈活的安全性和監控功能。