神刀安全网

用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

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

转载本站任何文章请注明:转载至神刀安全网,谢谢神刀安全网 » 用Swagger调用Harbor Registry的REST API

分享到:更多 ()

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址