首頁 部落格 SwaggerHub 101 回顧...

SwaggerHub 101 回顧：您最關心的 SwaggerHub 問題解答

Ryan Pinkham
  2016 年 10 月 04 日

我們最近推出了 SwaggerHub 使用者的免費培訓。 這些培訓旨在透過介紹 SwaggerHub 的不同功能和平台的功能，協助您充分利用 SwaggerHub。 您可以在此處找到即將推出的所有「SwaggerHub 101」培訓課程的完整清單。 作為培訓的一部分，參加者可以向 SwaggerHub 團隊成員尋求解答。以下是我們在最近的 SwaggerHub 101 培訓中收到的最常見問題回顧：

「顯示註解」是什麼？它如何運作？

「註解」功能是 SwaggerHub 的內建協作功能之一，可讓不同的關係人針對 SwaggerHub 編輯器內的 API 定義發表註解。協作者可以根據他們參與 API 設計流程所需存取的權限量，被指派特定的角色。例如，協作者可以被賦予編輯 API (編輯者)、註解 Swagger 規格個別行的權限 (註解者) 或單純檢視 API (檢視者)。使用註解來討論想法或在 SwaggerHub 編輯器中指出 API 定義特定行的問題。 註解 註解可用於分享意見反應或提出問題，並可標記為開啟或已解決。「顯示註解」按鈕將會顯示所有註解，包括開啟和已解決的註解。 深入了解如何使用 SwaggerHub 協作。

SwaggerHub 支援 JSON 或 YAML 嗎？

SwaggerHub 支援 Swagger (Open API) 2.0 用於描述 API 的語法。API 定義的預設格式為 YAML。您也可以貼上 JSON 文字，但儲存 API 定義時會將其轉換為 YAML 格式。 您可以 以下載 YAML 和 JSON 兩種格式的 Swagger 規格。

在 SwaggerHub 中發佈 API 時會發生什麼事？

發佈是一種告知他人 API 處於穩定狀態的方式，它將按照設計運作，並準備好被應用程式使用。 在 SwaggerHub 上發佈 API 時，該 API 會變成唯讀，且只有在 API 再次取消發佈時才能進行編輯。如果您需要改進描述文字或修正錯字，可以暫時取消發佈 API。但對於重大變更 (例如新的運算或參數)，您應該改為使用 SwaggerHub 編輯器中的 新增版本 命令來啟動新的 版本。 SwaggerHub 可讓您維護 API 規格的多個版本，因此您可以在保持已發佈的版本 (「生產」版本) 不變的情況下，繼續開發下一個 API 版本。 深入了解如何在 SwaggerHub 上發佈 API。

SwaggerHub 中有哪些可用的整合？

SwaggerHub 旨在供團隊在整個 API 生命週期中進行協作。因此，SwaggerHub 支援團隊開發 API 時所依賴的工具。 這些整合包括： 深入了解 SwaggerHub 的可用整合。

如何模擬 API 後端伺服器？

SwaggerHub 與 VirtServer 整合，VirtServer 是 SmartBear Ready! API 虛擬化產品的一部分。啟用後，VirtServer 整合會自動建立和維護在 SwaggerHub 中定義的 API 半靜態模擬。每次儲存 API 時都會更新此模擬，表示您不再需要尋找和使用外部工具來建立模擬服務。您可以利用 VirtServer 產生的預覽，與您的團隊有效率地重複執行設計，只需按幾下滑鼠即可完成。 在仔細考慮 API 設計時，模擬伺服器可能是一項強大的工具。無需撰寫任何程式碼，您就可以讓 API 消費者針對 VirtServer 開發用戶端，保證能回傳相容且真實的酬載。 深入了解如何使用 SwaggerHub 模擬 API。

SwaggerHub 如何協助撰寫我的 API 文件？

SwaggerHub 可提供以下關於文件的功能。
  1. 使用者可以直接在 Swagger 編輯器上定義和記錄 API 的每個方面，並可在 互動式文件 索引標籤中看到視覺化呈現，供最終使用者使用、理解和整合。
  2. 使用者可以透過我們內建的 API 的 HTML 下載功能，產生一個基本的開發者入口網站介面。您可以下載 API 文件的一個引導版本，其中會顯示您的端點以及 6 個不同的客戶端 SDK，而且您隨時可以新增更多。  
swaggerpetstore2 請按照以下步驟取得 HTML 渲染結果： 步驟 1：前往 SwaggerHub 上您其中一個有效的 API 步驟 2：點擊右上角的下載圖示，並從客戶端下載中選擇 html2 選項 publish-swagger 步驟 3：將 zip 檔案下載到您本機上的已知位置。前往下載位置，解壓縮資料夾，然後開啟下載的已解壓縮資料夾中的 HTML 檔案。

是否有計畫提供可以連接到內部部署 SCM 系統的已部署版本？

有。SwaggerHub 已有內部部署版本，目前已可使用。這是 Enterprise SwaggerHub 方案的一部分。若要了解內部部署版本是否適合您的組織，最好的方式是直接聯繫 SwaggerHub 團隊，電子郵件地址為 [email protected]。

錯過訓練課程了嗎？觀看隨選影片。

或註冊參加即將到來的訓練課程。
還有其他關於 SwaggerHub 的問題嗎？請寄電子郵件至 [email protected] 或在 Twitter 上聯絡我們：@SwaggerHub。

您可能也會喜歡