如何用Swagger調用Harbor Registry的REST API

這篇文章給大家介紹如何用Swagger調用Harbor Registry的REST API，內容非常詳細，感興趣的小伙伴們可以參考借鑒，希望對大家能有所幫助。

Swagger簡介

Swagger是最流行的RESTful API開源工具，含有一整套代碼庫、編輯器、代碼生成器等，可用于API的描述、定義、生成以及可視化等方面。我們可以在http://www.swagger.io 查看它的詳細介紹，下載它的源碼并集成到項目中來。Harbor是VMware新近開源的企業級容器Registry項目(http://github.com/vmware/harbor)，用戶可在私有環境中部署Harbor，實現容器鏡像的權限管理、圖形化管理、LDAP/AD認證集成以及日志審計等功能。Harbor還提供RESTful API，其他容器管理平臺可以很方便地集成Harbor的功能。本文介紹如何使用Harbor內嵌的Swagger工具，調用和測試RESTful API。

首先，我們來看看Swagger如何描述和定義RESTful API。Swagger提供在線所見即所得的編輯器（http://editor.swagger.io/），用戶可以在編輯器左側輸入符合Swagger規范的YAML或JSON配置，右側會根據輸入的內容實時顯示出實際的效果，如果輸入有錯誤，還會有提示出來教你如何改正，真的很方便！如何編寫符合規范的Swagger定義文件請參考（http://swagger.io/specification/）。

這個編輯器還支持將編輯好的YAML文件下載到本地，或者轉換成JSON格式，甚至還可以幫我們自動生成測試的服務端（Mock Server）或客戶端，還有很多功能我們都可以去嘗試。

使用Swagger的目的無外乎兩點：前后端的分離，按照契約進行測試。所謂前后端分離，是指前后端分別有著各自的開發流程、構建工具、測試等，通過RESTfulAPI來實現解耦，使得結構清晰，關注點分離；按照契約進行測試，是指前后端開發人員按照發布服務的請求路徑，參數，類型達成一致，形成契約，它可能是JSON或者是YAML格式的。在實際開發過程中，契約的形成是一個不斷完善的過程，肯定會經過多次修改、補充，Swagger恰恰滿足了這樣一個不斷變化完善的需求，實現前后端的分離，在進行契約測試時盡早的發現差異，做出調整，將最后集成的風險降至最低。

Harbor內嵌的Swagger功能

Harbor的核心功能也采用RESTful API來實現，在開發過程中采用Swagger編寫了一套可視化API規范，并作為項目的一部分提供給用戶使用。

Harbor項目采用兩種方式供用戶使用Swagger來展現或操控RESTful API。

一種是“靜態方式”，僅用Swagger來作為Harbor RESTful API 的展現和查閱工具。用戶只需從Harbor項目docs/目錄下找到swagger.yaml文件，用編輯器打開，全選、復制，粘貼到Swagger在線編輯器的左側代碼區，右側就會呈現出可視化的Harbor RESTful API文檔頁面，便于查閱和參考。

另一種是“動態方式”，將Swagger UI與Harbor REST服務部署在同一個Server中，用戶可以使用Swagger來操控并測試Harbor的RESTful API。此方法可能會修改數據庫中的數據，因此不建議在生產系統中使用。部署方案如下圖所示：

在Harbor項目源代碼的docs/目錄下，有個prepare-swagger.sh的腳本文件，可以幫助用戶實現“動態方式”部署。下文對相關步驟做簡要的說明，詳細信息請參閱文檔docs/configure_swagger.md:

（1）修改腳本文件中的SERVER_IP值，設置為當前部署Harbor系統的宿主機IP地址，保存修改后，執行該腳本。腳本會依次幫用戶下載Swagger軟件，解壓至Harbor項目vendors靜態資源目錄；將docs/目錄下的swagger.yaml文件拷貝至Harbor項目resources/yaml靜態資源目錄；根據用戶提供的SERVER_IP替換修改URL內容。

（2）切換到Deploy目錄，修改docker-compose.yml這個文件，將新添加的Swagger靜態資源目錄通過volumes方式掛載到HarborUI的Dockercontainer中，使得SwaggerUI可以隨著HarborUI啟動后一同發布給外部進行訪問。

（3）用docker-compose命令重新構建Harbor項目，清理之前遺留的容器內容，重新啟動新構建好的Harbor項目鏡像。

下圖是部署好的Swagger UI頁面截圖。

RESTful API認證問題

通過Swagger UI 來觸發Harbor RESTful API時還需要注意“登錄狀態”問題，因為部分API需要有session的信息。有兩種方法來配置。

方法一：先通過瀏覽器打開UI界面（注意：請務必保證Harbor UI的URL中的IP地址與之前部署Swagger UI是提供的SERVER_IP值是相同的），完成注冊（首次使用）、登錄；然后在同一瀏覽器中打開新的標簽(tab)頁面，輸入如下Swagger UI地址，這樣就能確保在用戶登錄的狀態下操控HarborRESTful API：

http://<server_IP>/static/vendors/swagger/index.html

方法二：Harbor RESTful API 本身實現了Basic Authentication 認證模式，但由于目前Swagger不支持從界面上輸入用戶名、密碼，造成訪問上不方便，感興趣的同學可以參考下面的鏈接（https://github.com/swagger-api/swagger-ui），嘗試修改Swagger實現Basic Authentication模式訪問。當然，用戶也可以用命令

curl -u <用戶名:密碼>

的方式來訪問API，這樣就可以不用事先登錄HarborUI來直接調試API了。

關于如何用Swagger調用Harbor Registry的REST API就分享到這里了，希望以上內容可以對大家有一定的幫助，可以學到更多知識。如果覺得文章不錯，可以把它分享出去讓更多的人看到。