用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镜像