nodeJS+swagger部署描述REST接口实战

主要章节

搭建nodeJS+swaggerUI环境

自定义接口描述文件并使用

解决跨域问题

搭建nodeJS+swaggerUI环境

1、下载swaggerUI代码

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

2、安装express

1、安装nodeJS；

2、新建一个空目录；

3、在目录下执行【npm init】，然后一路回车即可；

4、最后执行【npm install express –save】即可完成对express的安装。

3、添加swagger官方demo

1、在目录下新建public目录；

2、将swagger目录dist下文件尽数拷贝到public目录下。

4、编写nodeJS启动脚本

新建index.js并在其中编写如下代码：

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

app.use('/v1/api', express.static('public'));
app.use('/', function(req, res){
res.write('You maybe access /v1/api');
res.end();
});

var server = app.listen(8002, function (){
console.log('Example app listening on port 8002!');
});
// 设置服务永不超时
server.setTimeout(0)

5、启动swaggerUI

1、执行命令【node index.js】即完成对swagger的启动；

2、通过浏览器访问【http://ip:8002/v1/api】即可以访问到swagger官方的API demo UI。

接下来我们采用自定义接口描述文件swagger.json替换官方demo。

自定义接口描述文件并使用

1、编写接口描述文件swagger.json

描述文件编写规则见：

https://swagger.io/docs/specification/2-0/describing-request-body/

使用swagger edit在线编辑器编辑：

https://editor.swagger.io/

这部分可以通过yaml语法编辑，完成后选择保存为json文件swagger.json.

2、使用swagger.json替换官方demo

1、将编写完成swagger.json放入public目录；

2、打开public/index.html，将其中的【url: “…”】更换为【url: “swagger.json”】；

3、重新【node index.js】，然后打开浏览器即可看到类似如下的页面：



加载成功。

4、上图右下角有个错误，是无法是被swagger.json为url所致，解决办法是：打开public/index.html，在【url: “…”】同级添加【validatorUrl: false】即可。

解决跨域问题

完成以上步骤以后，你所自定义的接口即可通过swaggerUI的方式展示在人面前，便于查看。

但是当具体点击某一个接口并进行【Try it】的时候，你会发现并没有成功，调出浏览器调试页面后，你会发现是跨域问题。

这是因为，swagger是纯粹的前端，它并没有后台的支持，所有界面上接口的请求都是直接由ajax发起，而此时你的服务端获取并不支持跨域，所以便出现了跨域的问题。

解决方案有两种：

1、拦截swaggerUI的请求，统一由nodeJS做转发

由于需要涉及swaggerUI源码的东西，对我不适用，故放弃。

有兴趣的同学可以研究一下。

2、在服务端添加支持跨域请求的代码

对于get、post请求，是直接发送的具体请求的，在返回头添加（’Access-Control-Allow-Origin’, ‘*’）即可：

response.headers['Access-Control-Allow-Origin'] = '*'

而对于put、delete请求来说，当你【Try it】测试接口的时候，打开浏览器调试界面，可以发现其发送的是options请求，而查看服务端日志，收到的也是options请求。原来put、delete请求在发送之前首先会发送一次options请求，用来验证服务端是否支持跨域等操作。

处于这种情况，需要在服务端为这类请求添加options请求处理方法，并应swagger添加以下部分的东西后，测试成功。

response.headers['Access-Control-Allow-Origin'] = '*'

accessMethod = 'GET, POST, DELETE, PUT, PATCH, OPTIONS'
response.headers['Access-Control-Allow-Methods'] = accessMethod

accessHeaders = 'Content-Type, api_key, Authorization'
response.headers['Access-Control-Allow-Headers'] = accessHeaders

本人邮箱：

zhao.yj@yahoo.com

欢迎留言交流！！