文档章节

用Swagger调用Harbor Registry的REST API

project_harbor
 project_harbor
发布于 2016/04/21 11:26
字数 1559
阅读 1393
收藏 12

本文原作者为开源企业级容器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_Editor_for_Harbor_API.png



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

swaggerDeployment.png



在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页面截图。

Listed_Swagger_UI_for_Harbor_API.png



Detailed_show_of_Swagger_UI_for_Harbor_API_.png



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


© 著作权归作者所有

project_harbor
粉丝 16
博文 10
码字总数 18030
作品 0
海淀
私信 提问
Spring boot中使用Swagger2

问题 最近需要做接口开发,给客户端们调用,但是我又不想写文档,听说REST风格的接口都在用Swagger做IDL(Interface description language),中文就是接口描述语言,简单的说就是给调用方的...

亚林瓜子
2018/09/11
145
0
Harbor用户机制、镜像同步和与Kubernetes的集成实践

Habor是由VMWare公司开源的容器镜像仓库。事实上,Habor是在Docker Registry上进行了相应的企业级扩展,从而获得了更加广泛的应用,这些新的企业级特性包括:管理用户界面,基于角色的访问控...

msj0905
2018/06/27
0
0
开源Registry项目Harbor源代码结构解析

上周我们介绍了Harbor开源企业级容器Registry的架构,获得了社区很多朋友的反馈和建议,再次一并感谢,希望和大家一起,共同建设一个优秀的开源项目。本文请Harbor项目工程师尹文开介绍源码结...

project_harbor
2016/04/11
181
0
Harbor 1.8开拓镜像管理崭新应用场景

版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。 https://blog.csdn.net/q48S71bCzBeYLOu9T0n/article/details/90745645...

q48s71bczbeylou9t0n
06/02
0
0
Harbor: 跨数据中心复制Docker镜像的开源实现

容器镜像复制和发布一直缺少良好的工具,是实际开发和运维中的一大痛点。开源Harbor Registry提供强大的镜像复制/同步能力,成为众多用户喜爱的杀手级功能。本文介绍了镜像复制功能的工作原理...

project_harbor
2016/08/05
3K
0

没有更多内容

加载失败,请刷新页面

加载更多

记一次项目启动报java.lang.StackOverflowError

项目是spring boot,之前没有问题,突然有一次debug方式启动的时候报这个错误。 因为其他同事没有问题,线上也没有问题,所以先排除了是代码问题。 开始以为电脑开的软件太多,然后给jvm的内存...

chro008
7分钟前
5
0
idea 2019.2免费激活码

亲测有效到2020.6 812LFWMRSH-eyJsaWNlbnNlSWQiOiI4MTJMRldNUlNIIiwibGljZW5zZWVOYW1lIjoi5q2j54mIIOaOiOadgyIsImFzc2lnbmVlTmFtZSI6IiIsImFzc2lnbmVlRW1haWwiOiIiLCJsaWNlbnNlUmVzdHJpY3Rpb......

Iverson58
15分钟前
3
0
移动APP开发中的重要注意事项

您的移动app在变化吗?如果没有,请确保遵循这些提示进行移动app开发。大多数行业的IT领导者都优先考虑劳动力和消费者的移动性。实现成功的移动app开发具有挑战性,涉及在app功能开发的基础上...

a429011717
22分钟前
5
0
Qt编写自定义控件69-代码行数统计

一、前言 代码行数统计主要用来统计项目中的所有文件的代码行数,其中包括空行、注释行、代码行,可以指定过滤拓展名,比如只想统计.cpp的文件,也可以指定文件或者指定目录进行统计。写完这...

飞扬青云
40分钟前
10
0
驰骋工作流引擎-ccflow关于 “ 是否自动计算未来的处理人”的功能变更

关键字:流程未来节点处理人 工作流快速开发平台 工作流流设计 业务流程管理 asp.net 开源工作流 业务背景:一个流程在启动起来后,是可以对一些节点计算出来处理人是谁,流程的走向。对于另...

孟娟
56分钟前
5
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部