让接口测试成为合格的桥梁——本地搭建 Swagger-UI 环境搭建

Posted 2021-04-24 TesterHome

前言

接口测试是自动化测试过程中,投入产出比相对而言比较大的工作,我们组之前一直在用Jmeter执行接口测试工作,然后通过Jenkins调度执行Jmeter,给出测试报告。

测试报告如下:

痛点

• 客户端开发不能在线调试某个接口

• 客户端开发仍然需要跟服务端开发对接接口，我们组不能成为一个好的桥梁

• 我们接口测试反馈的结果，服务端开发和客户端开发同学都很少关注

明确了存在的问题之后，又经过跟客户端同学开发的调研，发现他们希望我们在测试过接口之后，有这样一个页面，可以供他们使用。

需求：

• 可以让他们在线调试接口

• 可以让他们明确看到有关接口的定义

• 可以让他们有正确可执行的curl命令

• 可以看到有关这个接口的当前是否可执行的状态

显然这个时候我们展示的html静态页面，已经不能达到他们的需要了。

由于服务端开发接口开发完毕之后，提供了Swagger UI页面，但是他们可能由于某些原因，并没有设置header，导致客户端开发基本不能调试，只能作为对接口的参数设置的大致了解，并没有起到相应的效果。

我们的思路就是借鉴服务端开发使用的Swagger UI，定制化我们自己需求的既可以展示Jmeter执行结果，又能让开发在线调试的页面。

Swagger UI

工欲善其事必先利其器，我先大致了解了一下Swagger UI。
Swagger UI是一个API在线文档生成和测试的框架。

优点

• 方便测试人员和客户端开发了解API

• 页面简单直接，方便调试

着手本地部署

（1）下载Swagger UI

git clone https://github.com/swagger-api/swagger-ui.git

（2）创建一个空文件夹mkdir swagger

（3）初始化，并创建package.json文件npm init

（4）安装express

npm install express --save

（5）在swagger中创建目录public,并将刚才clone下来的Swagger UI中dist目录下的所有文件全部复制到public目录下面。

（6）创建并修改swagger.js

var express = require('express');
var http = require('http');

// 接口显示页面
app.use('/static', express.static('public'));
app.listen(8005, function () {
  console.log('app listening on port 8005!');
});

（7）启动服务

cd swagger/
node swagger.js

打开http://127.0.0.1:8005/static/index.html，可以看到在线的官方的Demo已经在本地搭建好了。

改造之旅

第一步，希望替换官方的API

需要用到Swagger Editor生成一个合格的Swagger UI依赖的Spec。

可以通过，当然我推荐是自己本地部署一个Swagger Editor，因为官方的这个链接，虽然我的网络是有代理的，但是在使用过程中会连接中断，使用体验并不好。

插播一句Swagger Editor的本地部署

其实特别简单,git clone + npm intall。

本地安装Swagger Editor

git clone https://github.com/swagger-api/swagger-editor.git

npm install

启动本地的Swagger Editor，http://127.0.0.1:3001，可以看到这样的页面。

当然这是官方的例子。

可以导出为json格式的文件（这是我们需要的最重要的产物）。

可以参考官方的文档，编写正确的符合格式的Spec。

小贴士：因为我们部署的Swagger UI是2.0的版本，未使用3.0是因为，感觉3.0的源码我更看不懂。

配置json文件

将导出的data.json放置在swagger/public/data/下，并且修改一下swagger/public/index.html

if (url && url.length > 1) {
      url = decodeURIComponent(url[1]);
  } else {
      url = "/static/data/data.json";}

重启node swagger.js，然后重新打开浏览器，可以看到自己根据服务端API编写的API文档。

第二步解决跨域问题

本地部署好Swagger UI之后，虽然生成的curl命令是正确的，但是点击try it out，返回值一直是no content，经过查阅确认是因为javascript存在的同源问题。那么怎么解决呢？

这里要感谢我同事的帮忙，帮忙一起解决了。

解决的思路：

在swagger.js中，封装了一个真正向服务端发请求的方法/getResponse

app.use('/getResponse', function(req, response){

    var headers = {
      'aa': req.headers.aa,
      'xx':req.headers.xx,
      'content-type': req.headers["content-type"]
    };

    if(req.query){
        path = req.path.replace('/getResponse', '')  + "?" + querystring.stringify(req.query)
    }else{
        path = req.path.replace('/getResponse', '')
    }
    var options = {
        hostname: config_data.host,
        path: path,
        headers: headers,
        method: req.method
    };

    var req = http.request(options, function(res) {
        res.setEncoding('utf8');
        res.on('data', function (chunk) {
            response.send(chunk);
            console.log('返回值: ' + chunk);
        });
    });
    req.on('error', function(e) {
        console.log('problem with request: ' + e.message);
    });

    req.write(querystring.stringify(req.body));
    req.end();
});

在public/swagger-ui.js中,修改Operation.prototype.urlify = function (args, maskPasswords)。

 

将url值替换，实现对请求的拦截。

var url = '/getResponse';

这样,Swagger UI直接点击try it out之后，请求是先发到node 

swagger.js，然后由swagger.js再向服务端真实发出请求，再将返回值，塞给Swagger UI解析展示。

当然过程中有body不能解析的情况，需要安装库

npm install multer --save

并加入代码

var bodyParser = require('body-parser');var querystring = require('querystring');app.use(bodyParser.json());app.use(bodyParser.urlencoded({
  extended: true}));

这个时候，在Swagger UI页面点击try it out，已然可以真正的请求成功，也能让开发开始在线调试API了。

Jmeter执行结果显示

这里我其实走了取巧的方法，在生成的Swagger Editor中，如果配置如下，可以看到，Swagger Editor中，我的配置是这样的

我将tags中加入了Jmeter执行的结果，在具体接口信息中，将Summary字段也变成了Jmeter执行的结果。

最后在Swagger UI界面可以查看这里的json文件展示的样式：

可以说，手动尝试部分已经全部走通了，需要做的是将Jenkins调度Jmeter执行生成的jtl传递给Swagger UI。

将Jmeter执行结果传递过来

分两步：

• 用python将Jmeter生成的jtl，转化成我们需要的格式的json，主要参照

  {"info": {    "version": "0.0.0",    "title": "测试服务端API"}, "tags": [    {        "name": "测试一下",        "description": "【Jmeter build result】PASS"    }], "paths": {    "/aa.aa.aa.json": {        "get": {            "parameters": [                {                    "description": "自已",                    "default": "-1",                    "required": "是",                    "in": "query",                    "type": "INT64",                    "name": "fuid"                }            ],            "produces": [                "application/json"            ],            "tags": [                "测试一下"            ],            "summary": "Jmeter result: true 2017-03-30 19:04:12",            "consumes": [                "application/x-www-form-urlencoded"            ]        }    }}, "host": "test.test.com", "swagger": "2.0", "schemes": [    "https"]}

• 在swagger.js中编写一个upload API，可以将上一步生成的.json文件传递过来。

安装multer库

npm install multer --save

upload API

var storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, __dirname + '/public/data/');
  },
  filename: function (req, file, cb) {
    cb(null, file.originalname);
  }});// 上传.json文件接口app.post('/uploads', upload.single('file'), function(req, res, next){
    var file = req.file;
    res.send({'status': 'UPLOAD SUCCESS'});});

这个时候，在Jenkins执行Jmeter 接口测试之后，将data.json传递给，Swagger UI，然后Swagger UI显示结果，并供客户端开发在线调试。

回顾一下

客户端开发的需求基本都能得到满足，可以在线调试，可以看到正确的可执行的curl命令，可以看到关于这个接口当前的执行情况。

当然我对Node的认识非常非常皮毛，临时看了点介绍，之前一点没有了解。可能有些地方有更好的实现方式，可是我没有了解到。

当然还有很多需要优化的地方：

ToDo：

• 关于接口的更详细的描述和参数的描述需要添加

• Response Body开发希望看到可以选择显示格式的，比如JSON | RAW | XML

• 可以将Paramters部分参数固定可选的模式，现在是有默认值，可填，可随意修改

参考文档