用Swagger調用Harbor Registry的REST API

本文原做者爲開源企業級容器Registry Harbor項目的工程師王錕，主要介紹如何使用Harbor內置Swagger來測試和調用Harbor的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了。

歡迎你們使用Harbor Registry和反饋意見，可到GitHub上的Issues區和咱們互動。也能夠關注公衆號：「亨利筆記」，在後臺發信息"入羣"，加入Harbor開源項目用戶羣交流。( https://github.com/vmware/harbor )

Harbor相關的文章：

企業級容器Registry開源項目Harbor架構簡介

開源Registry項目Harbor源代碼結構解析

用P2P方法快速分發Docker鏡像