Harbor之Swagger REST API

目录

• Swagger介绍
• Harbor Swagger预览
• 整合本地Harbor与Swagger

Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTFul 风格的 Web 服务。通过 Swagger，我们可以方便的、快速的实现 RESTFul API，同时它也提供UI界面，可以直观的管理和测试各个API接口，它还可以集成到各种开发语言中，大大提高了我们日常工作效率。

Harbor也提供这样一个东东，不过默认没有安装。

详细的安装说明，可以直接参考官方文档：https://github.com/goharbor/harbor/blob/master/docs/configure_swagger.md

我这里仅做一些简要配置说明。

Harbor Swagger预览

Harbor提供一种通过在线Swagger编辑器预览Harbor REST API信息的方式。在线编辑器的地址：http://editor.swagger.io/

不过使用在线Swagger编辑器，需要我们提供harbor的swagger.yaml文件，下面是这个文件的两个下载地址：

URL1：https://raw.githubusercontent.com/vmware/harbor/master/docs/swagger.yaml
URL2：https://github.com/vmware/harbor/blob/master/docs/swagger.yaml

只需要将文件内容直接粘贴到swagger在线编辑器的左边即可。或者在swagger编辑器页面通过File --> Importfile导入yaml。

整合本地Harbor与Swagger

当然，最好的方式，是直接将Swagger与我们自建的harbor服务整合，这样可以实现在线的接口测试。

1. 下载prepare-swagger.sh以及swagger.yaml到你本地的harbor目录，我这里就直接放到了/usr/local/harbor中：

wget https://raw.githubusercontent.com/goharbor/harbor/master/docs/prepare-swagger.sh https://raw.githubusercontent.com/goharbor/harbor/master/docs/swagger.yaml

2. 修改prepre-swagger.sh

# 指定harbor的协议，如https/http
SCHEME=<HARBOR_SERVER_SCHEME>
# 指定harbor的访问地址，如hub.test.com
SERVER_IP=<HARBOR_SERVER_DOMAIN>

3. 执行prepare-swagger.sh

chmod +x ./prepare-swagger.sh
./prepare-swagger.sh

4. 修改harbor的docker-compose.yml文件，如下：

...
ui:
  ... 
  volumes:
    - ./common/config/ui/app.conf:/etc/core/app.conf:z
    - ./common/config/ui/private_key.pem:/etc/core/private_key.pem:z
    - /data/secretkey:/etc/core/key:z
    - /data/ca_download/:/etc/core/ca/:z
    ## add two lines as below ##
    - ../src/ui/static/vendors/swagger-ui-2.1.4/dist/:/harbor/static/vendors/swagger/:z
    - ../src/ui/static/resources/yaml/swagger.yaml:/harbor/static/resources/yaml/swagger.yaml
    ...
    

5. 重建harbor容器

 docker-compose down -v && docker-compose up -d

6. 访问

https://<HARBOR_SERVER>/static/vendors/swagger/index.html

在使用 Harbor API 时，是需要 session ID 的，当我们未登录 Harbor 时，直接使用API将得不到任何结果，这里如果我们想使用 Swagger UI 点击访问API返回结果，那么需要在浏览器中先登录 Harbor Web UI，登录后新开一个tab，在这个tab访问 Harbor Swagger Web，将会得到正常的响应结果，因为这时session已经共享，会话认证通过