Published: 2017-09-10

Swagger-mock-server的一个尝试

Table of Contents

1 概要

在前后端分离的企业api开发流程中,有时候会面临前端同学等待后端同学实现接口的情况。 为了避免时间上的浪费,可以采取先制定API文档再前后端并行开发的方式。 前端同学可以直接调用接口获得临时性的假数据,而不影响工作流畅性。

Swagger规范是一种通用的api文档格式,本文记录的是根据swagger文档自动生成假数据的一次尝试。

项目Github地址见: imnisen/swagger-mock-server

声明:这个项目还不完善,目前的阶段是:“能用”。距离达到 “清晰合理的架构”,“简单明了的开发部署”,“完善的功能”目标还需要努力。如果你有更好的做法或者意见建议欢迎通过issuse或者email联系我。

该项目实现的功能是:根据swagger文档,mock server 来生成假数据,这样便于实际开发中,定义好api后,前后端并行开发。

该项目除了mock server以外还包含了查看接口ui和开发时使用的editor.

2 Mock Server

“Mock server”的实现是基于swagger的这个node 项目server目录 下面的内容是执行参考这里 生成的。

为了支持多种假数据生成的要求,对依赖的一个模块进行了hack, 所以安装使用的时候会发现有这么一步: cp swagger-router.js node_modules/swagger-tools/middleware/swagger-router.js, 实际上是替换了 swagger-router.js 里107行 getMockValue 函数。

这个hack的方法是参考了这篇 博文,然后修复实际使用中发现的一些问题。

3 UI

UI部分是采用的官方 的ui工具,为了方便直接将内容提取到了 ui/dist目录 下,该目录对应于这个 github目录 便于以后“手工升级”(汗)。

4 Editor

实际使用的体验是,mock server对于swagger语法解析的要求要比ui要求严格,也就是说有些不合swagger规范的写法ui可以辨识,但却会导致mock server 不能正常解析以至于不能正常启动,所以拥有一个严格的swagger语法编辑器显得挺重要。官方提供了swagger editor,但它不能方便地选择默认编辑的文件和自动保存,所以每次使用时得手动选择要编辑的文件,编辑完之后再保存回去,这使得整体流程有些复杂。好在上面的swagger node项目里包含了 swagger editor,所以我在 server/package.json 里简单配置了下,可以使用 npm run edit 命令直接运行一个监听9999端口的editor, 该editor直接编辑 doc/swagger.yaml 文件,并且所有改动会自动保存。

而且编辑swagger文件应该是开发阶段的行为,所以构建服务的时候,swagger editor并没有暴露出来对外使用(也就是说不能直接修改服务端的swagger文档)。另外一点是我还没有找到合适的方法。在服务器端使用docker部署时按需求定制swagger editor。留待以后探究。

5 安装使用和工作流

分位两个阶段:开发和部署。

开发的时候,因为要使用到editor所以推荐本地安装,依赖 npm ,需要全局安装npm包 swagger,并且在 server 目录下执行 npm install 来安装所需依赖,最后将hack的 swagger-router.js 复制到对应位置,启动的时候通过 npm run servernpm run edit 分别启动 mock server 和 打开编辑器, swagger ui 也可以启动,通过 docker-compose up -d swagger_ui 来启动,并且在7777端口可以查看,但因为有editor,其提供了视图所以不是很必须。

部署的时候不需要使用editor,所以使用docker compsoe可以直接启动mocker 和 ui, 并且通过7777和8888访问, server/Dockerfile 里干掉了大部分上面需要手动做的事情,还是比较方便的。

具体安装还请参考github项目里说明

6 参考资源

Author: Nisen

Email: imnisenATgmailDOTcom

Emacs 25.2.1 (Org mode 8.2.10)