express+ejs+swagger-ui-dist 打造及时更新的rest api 在线接口文档

以你之姓@ 2022-05-23 00:41 378阅读 0赞

Swagger 是restFul Api接口文档编写神器，这里介绍一个在nodejs环境下，应用express框架实现一个多项目接口文档服务器，并在云服务器上实现及时在线更新。

一、创建express工程

应用express 脚手架创建一个基于ejs模板引擎的工程，进入工程目录安装项目依赖

express restapi --view=ejs
    cd restapi
    cnpm install

二、添加依赖库swagger-ui-dist

npm install swagger-ui-dist --save

安装完成后我们的目录结构是这样的

![2018-05-29-155117.png][]

我们在项目的node\_modules 文件夹中找到我们刚才安装的swagger-ui-dist的依赖库文件夹，将index.html 复制一份到views文件下，并将其改名为api.ejs

![2018-05-29-155357.png][]

我们将api.ejs的文件中的内容作如下修改

![2018-05-29-155546.png][]

![2018-05-29-155758.png][]

三、创建接口文档路由

我们在public目录下新建一个swagger目录，这里目录下放置我们写好的swagger文档，比如api\_1.json和api\_2.yaml。分别是两个项目的接口设计文档。

接下来我们修改一个routes目录下的index.js路由文档，我们添加两个路由，/api1 /api2, 通过url参数向ejs模板传递对应的接口文档地址。

四、启动服务器

在终端执行 npm start 并可以通过访问 localhost:3000/api1 和 localhost:3000/api2访问两个项目对应的文档了。

五、应用阿里云搭建公网服务器

如果我们的swagger文档是放在github,coding来托管的，我们可以利用他们的webhook功能实现及时更新，同样在routes/index.js中添加一个路由，访问时执行shell命令，我们的目标是在public/swagger文件夹下执行「git pull」

var process = require('child_process')
    
    /* 应用git webhoot 调用该接口执行 shell  */
    router.get('/pull', function(req, res, next) {
    
      // 将swagger工程执行push命令行，服务器端自动执行git pull 及时保存更新
      process.exec('cd public/swagger;git pull');
    
      res.send('git pull ok');
    });

[2018-05-29-155117.png]: http://ohag8y1i2.bkt.clouddn.com/2018-05-29-155117.png
[2018-05-29-155357.png]: http://ohag8y1i2.bkt.clouddn.com/2018-05-29-155357.png
[2018-05-29-155546.png]: http://ohag8y1i2.bkt.clouddn.com/2018-05-29-155546.png
[2018-05-29-155758.png]: http://ohag8y1i2.bkt.clouddn.com/2018-05-29-155758.png