利用Swagger UI接口文档同步本地Mock数据-阿里云开发者社区

开发者社区> 我是小助手> 正文

利用Swagger UI接口文档同步本地Mock数据

简介: 什么是Mock Mock顾名思义是一种模拟。通常利用相同的接口来模拟出一个对象以代替真实对象,这样能有效隔离外部依赖,便于测试。对于前端开发,Mock作为重要一环,能带来很多好处: 前后端并行开发 模拟各种响应值,便于测试 可及早发现一些极端响应值下的页面布局问题等 背景 前端开发可简单分为三个阶段:并行开发阶段、联调阶段和测试阶段。
+关注继续查看

什么是Mock

Mock顾名思义是一种模拟。通常利用相同的接口来模拟出一个对象以代替真实对象,这样能有效隔离外部依赖,便于测试。对于前端开发,Mock作为重要一环,能带来很多好处:

  • 前后端并行开发
  • 模拟各种响应值,便于测试
  • 可及早发现一些极端响应值下的页面布局问题等

背景

前端开发可简单分为三个阶段:并行开发阶段、联调阶段和测试阶段。现在的前端项目大多为前后端分离,在开发、联调阶段不可避免要面对数据源的问题。


e5c66b5b0a5304cd4c66dbdf7cbe313a34b6d4a7

在联调阶段,各个环境已有真实数据,方便本地调试,我们一般会将接口指向真实数据源。如果有跨域限制的话,可利用Charles、Fiddler等调试代理工具来解决,也可以起一个本地Server:


const express = require('express');
const proxy = require('http-proxy-middleware');
const app = express();

app.use('/api', proxy({ target: 'your-api-url', changeOrigin: true }));
app.listen(3000);

如果还处在并行开发阶段,那我们就需要Mock数据,一般有以下几种常用方式:

1、拦截Ajax、Fetch请求
缺点:前端混入脏代码;无法有效模拟网络情况。

2、本地Mock Server
缺点:接口众多,创建和修改成本高。

3、YApi、Easy Mock的接口管理平台
缺点:灵活性不够。比如一些配置信息分散在各个接口,没法集中管理,修改成本高。

本文以笔者接触较多的Swagger为例,从一个侧面改善本地Mock Server需要不断创建接口的缺点。打开后端提供的Swagger UI地址的Network,发现有个api-docs文件。

0460f4464be492c15debd7daec6f3f1aac2768cd


这个JSON文件包含接口、请求方法、响应格式等信息。可以想见解析这个文件并不难,唯一比较麻烦的可能就是响应值的解析和类型转换。如果能适时同步数据到本地Mock Server,能省去不少乏味的体力活。

Talk is cheap

1、目标

  • 接口路径和Mock目录相对应,便于查找、修改
  • 以请求方法为文件名,一个方法对应一个文件,减少多人编辑冲突
  • 使用Mock.js包装响应值,易于模拟一些极端状况

2、解析JSON文件

前面我们提到解析JSON文件的难点主要在响应值类型的转换,这边我们利用Easy Mock的一个解析模块来做这件事情。


const swaggerParserMock = require('swagger-parser-mock');

const synchronizeSwagger = {
  init({ url, blacklist, outputPath }) {
    this.url = url;
    this.blacklist = blacklist;
    this.outputPath = outputPath;
    this.parse();
  },
  async parse() {
    const { paths } = await swaggerParserMock(this.url);
    this.generate(paths);
    console.log(paths);
  }
}

synchronizeSwagger.init({
  // Swagger api-docs地址
  "url": "your-api-docs-url",
  // 输出目录
  "outputPath": "./routes",
  // 黑名单,跳过一些不需要同步的api
  "blacklist": []
});

打印paths信息,格式大致如下:


"/path/foo": {
  "get": {
    "summary": "bar",
    "responses": {
      "200": {
        "example": "'@string'" // 模块为我们做的类型转化和Mock.js包装。
      }
    }
  },
  "post": {
    "summary": "baz",
    "responses": {
      "200": {
        "example": "'@string'"
      }
    }
  }
}


3、遍历接口。我们可以加入黑名单,过滤掉一些对前端没有用处的接口。减少干扰,提高可维护性。


const fs = require('fs');
const { join } = require('path');
const { promisify } = require('util');
const mkdirp = require('mkdirp');

const writeFile = promisify(fs.writeFile);
const mkdir = promisify(mkdirp);

const synchronizeSwagger = {
  // 遍历api path信息
  traverse(paths) {
    for (let path in paths) {
      if (this.blacklist.includes(path)) {
        continue;
      }

      for (let method in paths[path]) {
        const pathInfo = paths[path][method];

        if (!pathInfo['responses']['200']) {
          continue;
        }
        this.generate(path, method, pathInfo);
      }
    }
  }
}

4、生成Mock文件,可以添加注释等信息。


const synchronizeSwagger = {
  // 生成mock文件
  async generate(path, method, pathInfo) {
    const outputPath = join(__dirname, this.outputPath, path);
    const {
      summary,
      responses: { 200: responseOK },
    } = pathInfo;

    try {
      // 生成目录
      await mkdir(outputPath);

      const example = responseOK['example'];
      // 生成文件内容
      const template = this.generateTemplate({
        summary,
        example,
        method,
        path,
      });

      // 生成文件, 已存在的跳过,避免覆盖本地以及编辑的文件
      const fPath = join(outputPath, `${method}.js`);
      await writeFile(fPath, template, { flag: 'wx' });
      console.log(`增加Mock文件:${fPath}`);
    } catch (error) {
      /* eslint-disable no-empty */
    }
  },

  generateTemplate({ summary, example, method, path }) {
  // prettier-ignore
  // api path中的{petId}形式改为:petId
  return `/**
${summary}
**/
const Mock = require("mockjs");
module.exports = function (app) {
  app.${method}('/api${path.replace(/\{([^}]*)\}/g, ":$1")}', (req, res) => {
    res.json(Mock.mock(${example}));
  });
};`;
  },
}

5、启动Mock Server

以express为例,利用require动态特征我们来创建路由,映射到刚才创建的接口文件。

const fs = require('fs');
const join = require('path').join;
const express = require('express');

const app = express();
const port = process.env.PORT || 3000;

app.listen(port, function() {
  console.log(`server is listening ${port}`);
});

function scan(path, app) {
  const files = fs.readdirSync(path);

  for (let i = 0; i < files.length; i++) {
    const fpath = join(path, files[i]);
    const stats = fs.statSync(fpath);

    if (stats.isDirectory()) {
      scan(fpath, app);
    }
    if (stats.isFile()) {
      require(fpath)(app);
    }
  }
}

scan(join(__dirname, './routes'), app);

写在最后

至此我们就利用Swagger UI同步Mock数据,如果再加上cors、body-parser等Middleware,一个本地Mock Server基本成形。方便同步,我们将它加入npm scripts。


  "scripts": {
    "ss": "node ./synchronizeSwagger.js"
  },

执行npm run ss,就能生成相应的Mock数据和访问接口了。

fe50a37cfe4e4cde9a4a8f3fea64b3754dbe69be

aa642676c64d2136a68b04c9521db1c8d0112e10




原文发布时间为:2018年06月22日
原文作者:朱子彦小朋友

本文来源: 掘金 如需转载请联系原作者




版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
ML之FE:基于load_mock_customer数据集(模拟客户)利用featuretools工具实现自动特征生成/特征衍生
ML之FE:基于load_mock_customer数据集(模拟客户)利用featuretools工具实现自动特征生成/特征衍生
38 0
如何让接口文档自动生成,SpringBoot中Swagger的使用
在开发过程中,java后端需要与客户端进行交互,需要将后端的接口及参数写成文档给调用者查阅。一个问题也有此而生,需求改动频繁,接口设计也会随之改动,文档修改的不及时会带来很大的问题。 Swagger是一个自动生成文档的工具,可以在线查阅文档,减少了开发人员的负担,下面我们就来看看如何在SpringBoot中使用Swagger。
997 0
Elasticsearch 指南 [7.0] - Document APIs 文档接口
Elasticsearch 指南 [7.0] - Document APIs 文档接口
3318 0
jQuery EasyUI API 中文文档 - 树表格(TreeGrid)
TreeGrid 树形表格 扩展自 $.fn.datagrid.defaults,用 $.fn.treegrid.defaults 重写了 defaults。 依赖 datagrid 用法 1.
1017 0
jQuery EasyUI API 中文文档 - 数据表格(DataGrid)
DataGrid 数据表格 扩展自 $.fn.panel.defaults ,用 $.fn.datagrid.defaults 重写了 defaults 。 依赖 panel resizable linkbutton pagination 用法 1.
1083 0
kubeadm高可用master节点部署文档
kubeadm的标准部署里,etcd和master都是单节点的。 但上生产,至少得高可用。 etcd的高可用,用kubeadm微微扩散一下就可以。 但master却官方没有提及。 于是搜索了几篇文档,过几天测试一下。
1783 0
DSO(dsoframer)的接口文档
(开发环境)使用前先注册一下DSOFramer.ocx    操作:将DSOFramer.ocx复制到C:\windows\system32目录下,         开始->运行->regsvr32 DSOFramer.
722 0
阿里云短信使用入门/开发接口文档一篇文章全搞定
阿里云短信提供秒级触达到达率99%,国际/港澳台短信覆盖200多个国家和地区,阿里云短信接入简单
3449 0
jQuery EasyUI API 中文文档 - DataGrid 数据表格
扩展自 $.fn.panel.defaults ,用 $.fn.datagrid.defaults 重写了 defaults 。 依赖 panel resizable linkbutton pagination 用法 1.
996 0
+关注
我是小助手
云栖直播
384
文章
6
问答
文章排行榜
最热
最新
相关电子书
更多
《2021云上架构与运维峰会演讲合集》
立即下载
《零基础CSS入门教程》
立即下载
《零基础HTML入门教程》
立即下载