在我們不斷努力推廣 Swagger 的過程中，Swagger 團隊最近推出了 SwaggerHub，這是一個線上服務，它將核心 Swagger 工具（UI、編輯器、程式碼產生器、驗證器）整合到一個協作平台中，旨在讓您更容易開始使用 Swagger 及其工具。在這篇文章中，我將重點介紹 SwaggerHub 公開的對應 API，它允許您在 SwaggerHub 註冊表中搜尋、擷取、建立和更新 Swagger 定義。這讓您可以：
- 將 SwaggerHub 中 Swagger 定義的搜尋和擷取整合到現有的 API 工具中
- 直接將 Swagger 定義儲存到 SwaggerHub
SwaggerHub API 可在 https://app.swaggerhub.com/apis/swagger-hub/registry-api/ 取得，其 Swagger 2.o 定義可在 https://swaggerhub.com/api/swagger-hub/registry-api 取得。
SwaggerHub API 識別碼
在我們深入了解 API 本身之前，讓我們先快速看看 SwaggerHub 如何識別 API - 因為這個「方案」在 API 和 SwaggerHub 本身中都普遍使用。
SwaggerHub 中的每個 Swagger 定義都由以下值識別：
- 擁有者 - 擁有 API 的帳戶
- api - 擁有者帳戶下 API 的唯一識別碼
- 版本 - 唯一的版本識別碼
在 API 和 SwaggerHub 應用程式中，這些都按上述順序組合成路徑段，這讓您可以使用以下任一方式直接連結到 SwaggerHub 上的 API 及其 API：
https://swaggerhub.com/api/{owner}/{api}/{version}
或
https://api.swaggerhub.com/apis/{owner}/{api}/{version}
對於 SwaggerHub API，這些端點為：
如果您省略結尾的版本，您將獲得稍微不同的結果
- 網頁版本將顯示 API 的預設版本（可在 API 設定中設定）
- api 版本將傳回 API 所有版本的 apis.json 清單
apis.json
許多對 SwaggerHub API 的 GET 呼叫會傳回 apis.json 格式的 API 清單。例如，https://api.swaggerhub.com/apis/swagger-hub/registry-api 將傳回 SwaggerHub API 所有版本的清單。您可以在 apisjson.org 網站上閱讀有關 apis.json 格式的資訊。上述清單中的每個項目都包含許多 SwaggerHub 特有的自訂「X-??」屬性
- X-Version：SwaggerHub 中對應 API 的版本
- X-Created：版本在 SwaggerHub 中建立的時間
- X-Modified：版本上次在 SwaggerHub 中修改的時間
- X-Published：此 API 版本是否已在 SwaggerHub 上「發布」（表示它已處於最終狀態）
對於此特定清單，您應該在結果中取得（在撰寫本文時）3 個項目；版本 1.0.0、1.0.1 和 1.0.2 - 以及對應的中繼資料。
驗證
SwaggerHub API 公開的大多數資源不需要驗證權杖 - 目前唯一需要的是 POST 到 /apis/{owner}/{api} 的呼叫，它會建立/更新指定的版本（稍後會詳細說明）。若要進行此呼叫，您需要提供一個「Authorization」HTTP 標頭，其中包含您可以透過 SwaggerHub UI 取得的 API 金鑰，方法是執行下列步驟
- 選取右上角選單中的「設定」
- 選取左側的「API 金鑰」
- 按一下「建立 API 金鑰」
這個金鑰不僅可讓您在您的帳戶下張貼新的/更新的 API，還會為搜尋和 API 清單新增一些額外功能
- 一個額外的 X-UserRole apis.json 屬性，說明已驗證的使用者對特定 API 擁有的角色（擁有者、編輯、檢視）
- 可以指定 filter=user 作為 API 搜尋呼叫的查詢引數，它將僅傳回已驗證使用者有權存取（作為擁有者或協作者）的 API（X-UserRole 屬性將為「擁有者」或「編輯」）
搜尋 SwaggerHub 註冊表
好的 - 讓我們直接進入重點 - SwaggerHub API 的基本資源位於 https://api.swaggerhub.com/apis。
此資源將傳回 SwaggerHub 註冊表中所有公開 API 的分頁清單（在撰寫本文時，所有 API 都是公開的 - 但這在不久的將來肯定會改變）。如 Swagger 定義所示，有多個查詢引數可用於篩選
- query：在所有 API 的擁有者、名稱、swagger.info.title 和 swagger.info.description 上搜尋
- tag：僅傳回具有指定標籤的 API
- state：僅傳回具有指定狀態的 API
- page 和 limit：分頁
- sort 和 order：排序和排序 (!)
因此，舉例來說，如果您想要尋找已發佈的金融 API，您可以呼叫
在撰寫本文時，它會傳回一個 API - 太棒了！
如果您想要將搜尋範圍縮小到僅限特定擁有者的 API，請依照 swagger.json 中的說明將其新增至路徑
您可能會注意到，您從上述 API 呼叫獲得的結果與您在 SwaggerHub UI 中看到的結果完全相同，這僅僅是因為 SwaggerHub 在幕後將相同的 API 用於其所有 API 搜尋/擷取/更新功能。
搜尋結果中的 API 版本
如您所見，每個 {owner}/{api} 只會傳回一個項目 - 您不會獲得該 API 每個版本的項目。API 的預設版本會在 X-Version apis.json 屬性中傳回，以及其 Swagger 屬性中 swagger.json 的連結。此外，也會新增 X-Versions 屬性，其中包含該 API 所有版本的逗號分隔清單；已發佈的版本會加上星號作為前綴。
例如，fehguy 的家庭自動化專案在上述清單中具有以下屬性
這表示預設版本設定為 1.0.0，但還有其他版本可用（1.0.1 和 1.0.2）。它還表示唯一發佈的版本是 1.0.1。
將 API 識別碼新增至路徑將顯示該 API 的所有版本。例如，以下傳回 SwaggerHub 註冊表 API 的所有版本
https://api.swaggerhub.com/apis/swagger-hub/registry-api
擷取 API 定義
擷取 API 定義非常簡單，如上所示。只需使用端點 https://api.swaggerhub.com/apis/{owner}/{api}/{version} 以 JSON 或 YAML 格式擷取 Swagger 定義（預設為 JSON - 將 Accept 標頭設定為「application/yaml」以取得 YAML 版本）。如果您想要直接鎖定特定格式，您可以將 swagger.json 或 swagger.yaml 附加至端點。例如，SwaggerHub 定義的 JSON 版本可在 https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.0/swagger.json 取得。
建立/更新 API 定義
如上所述，一旦您準備好 API 金鑰，您就可以在 SwaggerHub 註冊表中建立和更新 Swagger 定義。只需將實際的 Swagger 2.0 定義 POST 到 https://api.swaggerhub.com/apis/{owner}/{api}。
以下規則適用
- 您只能更新/建立您帳戶下的 API - 即以您的使用者名稱作為擁有者。
- 目前，檔案必須包含語法有效的 YAML 或 JSON 內容。
- API 的版本將從 Swagger 定義中的 version 屬性擷取 - 如果遺失或無效，該定義將會遭到拒絕。
- 如果已存在具有該版本的 API 版本，它將會使用新的定義來更新（除非該版本已發佈 - 在這種情況下，更新將會遭到拒絕）。
就這樣！
簡單又直接 - 對吧？您可以如上所述直接在瀏覽器中玩轉 API（因為大多數呼叫都是 GET 呼叫），或者您可以使用 SwaggerHub 中的整合式 Swagger-UI，網址為 https://swaggerhub.com/api/swagger-hub/registry-api/1.0.0/ui（請注意結尾的「ui」- 它會在介面中自動選取 Swagger-UI 標籤）。
現在就用您的整合來吸引我們吧 - 我們很樂意在 https://swagger.dev.org.tw 上分享它們。如果您想查看實際的整合範例，請參考 Ready! API SwaggerHub 外掛的原始碼，網址為：https://github.com/SmartBear/readyapi-swaggerhub-plugin。
Swagger 加油！