Swagger-mock-server的一个尝试

1. 概要
2. Mock Server
3. UI
4. Editor
5. 安装使用和工作流
6. 参考资源

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 server 和 npm run edit 分别启动 mock server 和打开编辑器， swagger ui 也可以启动，通过 docker-compose up -d swagger_ui 来启动，并且在7777端口可以查看，但因为有editor，其提供了视图所以不是很必须。

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

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