首頁 部落格 API 標準化...

API 標準化常見問題：關於使用 Swagger 工具大規模建構和實施 API 標準的熱門問題

Ryan Pinkham
  2019 年 1 月 3 日

在 12 月，我們在 SwaggerHub 中發布了強大的新功能，API 標準化，讓團隊能夠大規模建構和實施 API 樣式指南。

在新年之前，我們舉辦了一場免費培訓，使用 Swagger 大規模建構和實施 API 標準。在 60 分鐘的課程中，我們現場示範了新功能，並討論了組織如何使用 Swagger 工具和 OpenAPI 規格來標準化其 API 設計。

超過 1,000 人加入了課程，我們收到了大量關於團隊如何使用 SwaggerHub 和 OAS 來實施這些策略的問題。但我們也收到許多人由於年底繁忙的行程而無法參加網路研討會的回饋。

我們很高興宣布，在 1 月 10 日，我們將 舉辦網路研討會的特別重播！作為預覽，我們也想分享並回答第一次課程中的熱門問題。請查看以下內容，並務必 預訂您在 1 月 10 日美國東部時間上午 10 點和下午 2 點舉行的網路研討會名額。

SwaggerHub 中的新 API 標準化功能是否支援從我們的內部樣式指南新增自訂規則的選項？

此功能在該功能的初始版本中不受支援。如果您有想要新增至 API 標準化的規則，請在 Twitter 上與我們聯繫 @swaggerhub。我們希望收到您的回饋，以便我們可以繼續開發該工具以滿足 API 團隊的需求。

當我們在 SwaggerHub 中啟用 API 標準化時，是否會將其應用於所有 API 和每個 API 版本？

API 標準化可讓您在組織層級設定規則，並讓這些規則應用於您在 SwaggerHub 中目錄中的所有 API 定義。當您建立定義的新版本或更新現有版本時，該功能會根據您帳戶中定義的規則自動驗證並提供回饋。

API 標準化是否適用於最新版本的 OpenAPI 規格 OAS 3.0？

是的，API 標準化支援 OAS 3.0，但有一些規則例外。您可以在下方查看完整的規則和例外清單：

操作

  • 必須存在 OperationId 且為非空字串

  • 必須存在操作摘要且為非空字串

  • 摘要應以大寫字母開頭並以點號結尾

  • 必須存在操作描述且為非空字串

  • 操作必須有一個標籤且為非空字串（僅限 OpenAPI 2.0）

  • 操作必須有一個且僅有一個標籤

  • 操作必須至少有一個 2xx 回應

  • 操作必須有一個預設回應

API 資訊

  • API 標題必須存在且為非空字串

  • API 描述必須存在且為非空字串

  • API 聯絡人必須存在且為非空字串

  • API 授權必須存在且為非空字串

模型

  • 所有模型屬性都必須有範例（僅限 OpenAPI 2.0）

  • API 不得有本機定義（即僅允許 $refs）（僅限 OpenAPI 2.0）

您是否對我們如何從程式碼產生定義有任何建議？我們在為現有 API 產生有用的介面時遇到問題？

有一些開源工具和程式庫可以協助從現有 API 產生 OpenAPI 定義。Swagger 團隊支援其中一些程式庫，以從您的現有 API 產生 OAS，其餘的則由 OAS 社群維護：

您可以在此處探索其他支援 OAS 的開源工具。

我們可以建立可在多個規格檔案中重複使用和參考的通用模型嗎？

SwaggerHub 透過網域功能支援此功能。網域是可以儲存在 SwaggerHub 中並從 SwaggerHub 編輯器中在定義中參考的可重複使用元件。

網域可以包含以下元件（它們的任何組合）：

  • 定義 – 描述您的 API 輸入和輸出的資料模型。

  • 路徑項目 – 可在 API 之間重複使用的 API 路徑（例如 GET、POST、PUT 操作）。

  • 參數 – API 呼叫的參數：路徑參數、查詢字串參數、自訂標頭、主體欄位。

  • 回應 – API 呼叫傳回的回應：HTTP 狀態碼和回應資料模型。

了解更多資訊

SwaggerHub 是否與我們的原始碼控制存放庫搭配使用？

SwaggerHub 提供與 GitHub、Bitbucket 和 GitLab 的原始碼控制整合。此整合可讓您將 API 定義、自動產生的伺服器程式碼或用戶端 SDK 與現有的存放庫同步。每次您在 SwaggerHub 中儲存 API 時都會執行同步。您可以完全控制將在目標存放庫中新增、更新或忽略哪些檔案。

您現在可以利用 SwaggerHub 作為所有 API 設計和文件需求的單一來源，而不是將您的 OAS 定義託管在 GitHub 的各種儲存庫和分支中，同時仍然保持它們與您在 GitHub 或任何其他原始碼控制儲存庫中的原始碼同步。

了解更多

我們應該使用哪些衡量標準來確定 API 品質？

在網路研討會中，我們預覽了 2019 年 API 狀態報告中的新數據，該報告將於 2019 年 1 月發布。關於組織如何衡量品質，前三名的回應是：效能、可用性/開發人員體驗以及正常運行時間/可用性。我們還發現，用於提供高品質 API 的主要工具是：API 文件工具、API 功能測試工具、CI/CD 工具。

我們將在 1 月份分享更多報告中的見解，其中包括關於整個 API 生命週期（從規劃和設計到測試和監控）中品質觀點的詳細解讀。

Swagger 和 OpenAPI 之間有什麼區別？

理解 Swagger 和 OpenAPI 規範之間關係的最簡單方法是：

  • Swagger 是由 SmartBear 團隊支援和開發的一系列開放原始碼、免費和專業工具，這些工具支援 OpenAPI 規範。

  • OpenAPI 是規範的名稱，它受到 Swagger 工具和來自 Swagger 工具生態系統之外的不同供應商的數百種其他工具的支持。

該規範在 2015 年被捐贈給 Linux 基金會下的 OpenAPI 倡議後，正式更名。

了解更多

我可以查看對現有 API 所做的更改嗎？在接受這些更改之前是否有審查這些流程的過程？

SwaggerHub 能夠託管和維護 API 定義的多個版本。這意味著您可以擁有一個已發布的版本，該版本已準備好進行開發，並在 API 演進時繼續處理下一個版本的定義。

我們看到團隊追蹤 API 定義變更的方法之一是使用 SwaggerHub 編輯器中的註解功能。這讓您可以直接在編輯器中新增意見回饋、請求變更和解決問題。

在審查和合併對 API 的變更時，團隊可以利用 SwaggerHub 中的「比較與合併」功能。此功能可讓您將工作版本的定義中的變更與原始發布版本進行比較。作為架構師或經理，您可以視覺化地看到所做的變更，並選擇接受或拒絕這些變更。如果您有一組您知道想要在定義中強制執行的規則，並且不想手動審查和合併這些更新，您可以在組織設定中的「API 標準化」面板中選擇它們。

我們在 CI 管道中採用程式碼優先的方法。是否有可能進行自動化測試，從程式碼產生我們的 Swagger，將其提交到您的 API，並根據規則取得指示其是否有效的回應？

雖然我們看到許多團隊和組織透過其 Web 介面使用 SwaggerHub，但該平台底層的 API 同樣強大。如果您透過程式碼註解或框架動態產生 OpenAPI，只需對 Registry API 進行簡單的 POST 呼叫，即可驗證定義並將其儲存為較大型內部目錄的一部分。此工作流程不僅使提交新定義變得容易，而且也使提取定義以進行測試或文件編寫成為一個直接的過程。如果您有興趣更詳細地了解我們「程式碼優先」的方法，我們最近的網路研討會涵蓋了一些可用的工作流程和外掛程式。

了解更多

有興趣了解新的 API 標準化功能如何運作嗎？請在 1 月 10 日加入我們的特別網路研討會重播。 立即註冊

您可能也會喜歡