如何用Swagger調(diào)用Harbor Registry的REST API

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

Swagger簡(jiǎn)介

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

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

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

使用Swagger的目的無(wú)外乎兩點(diǎn)：前后端的分離，按照契約進(jìn)行測(cè)試。所謂前后端分離，是指前后端分別有著各自的開發(fā)流程、構(gòu)建工具、測(cè)試等，通過(guò)RESTfulAPI來(lái)實(shí)現(xiàn)解耦，使得結(jié)構(gòu)清晰，關(guān)注點(diǎn)分離；按照契約進(jìn)行測(cè)試，是指前后端開發(fā)人員按照發(fā)布服務(wù)的請(qǐng)求路徑，參數(shù)，類型達(dá)成一致，形成契約，它可能是JSON或者是YAML格式的。在實(shí)際開發(fā)過(guò)程中，契約的形成是一個(gè)不斷完善的過(guò)程，肯定會(huì)經(jīng)過(guò)多次修改、補(bǔ)充，Swagger恰恰滿足了這樣一個(gè)不斷變化完善的需求，實(shí)現(xiàn)前后端的分離，在進(jìn)行契約測(cè)試時(shí)盡早的發(fā)現(xiàn)差異，做出調(diào)整，將最后集成的風(fēng)險(xiǎn)降至最低。

Harbor內(nèi)嵌的Swagger功能

Harbor的核心功能也采用RESTful API來(lái)實(shí)現(xiàn)，在開發(fā)過(guò)程中采用Swagger編寫了一套可視化API規(guī)范，并作為項(xiàng)目的一部分提供給用戶使用。

Harbor項(xiàng)目采用兩種方式供用戶使用Swagger來(lái)展現(xiàn)或操控RESTful API。

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

另一種是“動(dòng)態(tài)方式”，將Swagger UI與Harbor REST服務(wù)部署在同一個(gè)Server中，用戶可以使用Swagger來(lái)操控并測(cè)試Harbor的RESTful API。此方法可能會(huì)修改數(shù)據(jù)庫(kù)中的數(shù)據(jù)，因此不建議在生產(chǎn)系統(tǒng)中使用。部署方案如下圖所示：

在Harbor項(xiàng)目源代碼的docs/目錄下，有個(gè)prepare-swagger.sh的腳本文件，可以幫助用戶實(shí)現(xiàn)“動(dòng)態(tài)方式”部署。下文對(duì)相關(guān)步驟做簡(jiǎn)要的說(shuō)明，詳細(xì)信息請(qǐng)參閱文檔docs/configure_swagger.md:

（1）修改腳本文件中的SERVER_IP值，設(shè)置為當(dāng)前部署Harbor系統(tǒng)的宿主機(jī)IP地址，保存修改后，執(zhí)行該腳本。腳本會(huì)依次幫用戶下載Swagger軟件，解壓至Harbor項(xiàng)目vendors靜態(tài)資源目錄；將docs/目錄下的swagger.yaml文件拷貝至Harbor項(xiàng)目resources/yaml靜態(tài)資源目錄；根據(jù)用戶提供的SERVER_IP替換修改URL內(nèi)容。

（2）切換到Deploy目錄，修改docker-compose.yml這個(gè)文件，將新添加的Swagger靜態(tài)資源目錄通過(guò)volumes方式掛載到HarborUI的Dockercontainer中，使得SwaggerUI可以隨著HarborUI啟動(dòng)后一同發(fā)布給外部進(jìn)行訪問(wèn)。

（3）用docker-compose命令重新構(gòu)建Harbor項(xiàng)目，清理之前遺留的容器內(nèi)容，重新啟動(dòng)新構(gòu)建好的Harbor項(xiàng)目鏡像。

下圖是部署好的Swagger UI頁(yè)面截圖。

RESTful API認(rèn)證問(wèn)題

通過(guò)Swagger UI 來(lái)觸發(fā)Harbor RESTful API時(shí)還需要注意“登錄狀態(tài)”問(wèn)題，因?yàn)椴糠諥PI需要有session的信息。有兩種方法來(lái)配置。

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

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

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

curl -u <用戶名:密碼>

的方式來(lái)訪問(wèn)API，這樣就可以不用事先登錄HarborUI來(lái)直接調(diào)試API了。

關(guān)于如何用Swagger調(diào)用Harbor Registry的REST API就分享到這里了，希望以上內(nèi)容可以對(duì)大家有一定的幫助，可以學(xué)到更多知識(shí)。如果覺得文章不錯(cuò)，可以把它分享出去讓更多的人看到。