本地搭建 Swagger-UI 环境搭建

源作者地址：https://testerhome.com/topics/8168

前言

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

痛点

客户端开发不能在线调试某个接口
客户端开发仍然需要跟服务端开发对接接口，我们组不能成为一个好的桥梁
我们接口测试反馈的结果，服务端开发和客户端开发同学都很少关注

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

可以让他们在线调试接口
可以让他们明确看到有关接口的定义
可以让他们有正确可执行的curl命令
可以看到有关这个接口的当前是否可执行的状态

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

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

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

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

方便测试人员和客户端开发了解API
页面简单直接，方便调试

着手本地部署

（1）下载Swagger UI

扫描二维码关注公众号，回复： 11322911 查看本文章

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，因为官方的这个链接，虽然我的网络是有代理的，但是在使用过程中会连接中断，使用体验并不好。
插播一句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。OpenAPI-Specification

小贴士：因为我们部署的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部分参数固定可选的模式，现在是有默认值，可填，可随意修改

参考文档

Swagger UI教程 API 文档神器搭配Node使用 web api 接口文档 mvc接口文档

基于swagger的RESTful API开发实践

本地搭建 Swagger-UI 环境搭建

猜你喜欢