转载

用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/harbo r)，用户可在私有环境中部署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调用Harbor Registry的REST API

另一种是“动态方式”，将Swagger UI与Harbor REST服务部署在同一个Server中，用户可以使用Swagger来操控并测试Harbor的RESTful API。此方法可能会修改数据库中的数据，因此不建议在生产系统中使用。部署方案如下图所示：

用Swagger调用Harbor Registry的REST 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页面截图。

用Swagger调用Harbor Registry的REST API

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_I P>/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开源项目用户群交流。

原文 http://dockone.io/article/1236

正文到此结束