swagger-to-umi-mock-server

Swagger 文档一健转 umi mock 服务 —— by 北森前端团队 beisen.com

特性

• 📦 开箱即用，umi 项目使用插件 umi-plugin-swagger-to-mock，非 umi 项目使用本项目提供的 umi-swagger-server 独立运行
• 🏈 支持 swagger json 多来源，可通过配置指定本地文件，也支持线上文件
• 🎉 数据格式可定制，可指定数据输出格式化
• 🚀 支持 mock api 和线上 api 热切换，通过配置 mock.js 文件提定具体的哪个 api 走 mock，哪个走线上
• 💈 支持数据 override，动态监听 override 目录，此目录里的 js 文件可精确将你的数据 merge 到指定 api 的返回数据，还可指定返回延迟时间
• 🐠 支持 mockjs，umi 和本插件均支持 mockjs 创建动态数据

快速上手

# umi项目安装
$ yarn add -D umi umi-plugin-swagger-to-mock
# or
$ npm install -D umi umi-plugin-swagger-to-mock

# 非umi项目安装
$ yarn add -D umi-swagger-server
# or
$ npm install -D umi-swagger-server

# umi项目启动(npm script)
$ PORT=8001 umi dev

# 非umi项目启动(npm script)
$ PORT=8001 umi-swagger-server

# 查看结果
$ curl -X POST http://localhost:8001/mock/store/order

项目目录结构

.
├── mock
│   ├── api.js // 普通umi mock文件，可省略
│   └── swagger.js // umi-plugin-swagger-to-mock 动态生成的mock文件
├── node_modules
├── package.json
├── src
│   ├── shared
│   │   └── api
│   │       ├── apiList.js // 动态生成的 api key 列表
│   │       ├── apiMap.js // 动态生成的 api key -> api路径列表
│   │       ├── apiPathToMockPath.js  // 用户自定义函数用于转换直实路径到mock路径
│   │       ├── apiRename.js // 用户自定义对象用于api重命名
│   │       ├── index.js // 动态生成，用户在代码中导入，可获得所有api的key到路径的映射
│   │       └── mock.js // 用户自定义mock文件，可以提定哪些api走mock路径
│   └── you-business-code.js
└── swagger
    ├── json // 分别为需要解析的swagger json文件,会动态遍历此目录
    │   ├── swagger.java.json
    │   └── swagger.net.json
    └── override // 你需要复写的api数据文件,会动态遍历此目录，同步更新mock/swagger.js
        ├── alipay.js
        ├── home.js
        └── team.js

文件详细说明

• src/shared/api.js 使用 umi 的 mock 功能

• src/shared/apiPathToMockPath.js 用户自定义函数用于转换直实路径到 mock 路径，一般用于代理识别和调试实别，可省略，默认值

module.exports = function(path) {
  return `/mock/${path.replace(/^\//, '')}`
}

• src/shared/apiMap.js 动态生成的 key-path 映射文件

{
 appList: '/queries/third/app/list',
 appList: '/queries/client/app/list',
 clientCheckstandById: '/queries/client/checkstand/{id}',
 ...
}

• src/shared/apiRename.js 用户自定义对象用于 api 重命名，因为来自 swagger json 的 api key，都取自 api 路径的最末尾两级路径，可能存在重复，如上面 apiMap.js 文件的 list key 重复，需要通过 apiRename.js 重命名

module.exports = {
  clientAppList: '/queries/client/app/list',
}

• src/shared/mock.js 用户自定义 mock 文件，可以指定哪些 api 走 mock 路径, 来源参考动态更新的 ./apiList.js

const { uniq } = require('lodash')
module.exports = uniq([
  //'appList', 注释掉指定API，将走线上
  'clientAppList', // 此API会走Mock服务器
  'clientCheckstandById', // 此API会走Mock服务器
])

• src/shared/index.js 动态生成，用户在代码中导入，可获得所有 api 的 key 到真实路径或 mock 路径的映射。有了映射关系，你就可以在 devServer 配置 Proxy 规则，或则配置 fetch 的 URL 拦截，路由到线上或 mock 资源

import api from 'shared/api'

fetch(api.appList, { method: 'POST' }).then(response => {...}) // 请求线上api
fetch(api.clientAppList).then(response => {...}) // 请求mock api
fetch(`${api.clientCheckstandById}${id}`, { method: 'POST' }).then(response => {...}) // 请求mock api

console.log(api)
-------------------
=> {
 appList: '/queries/third/app/list',
 clientAppList: '/mock/queries/client/app/list',
 clientCheckstandById: '/mock/queries/client/checkstand/',
 ...
}

配置.umirc.js

在项目根目录创建.umirc.js 文件

const path = require('path')
module.exports = {
  plugins: [
    [
      'umi-plugin-swagger-to-mock',
      {
        swaggerOutputPath: path.join(__dirname, 'src/shared/api'), // 可省略默认为src/shared/api
        swaggerPath: path.join(__dirname, 'swagger'), // 可省略，默认为swagger, 此目录须包含两个子目录json 和 override
        swaggerDocs: [
          // 可省略，默认为swagger/json目录下所有json文件
          {
            source: 'http://petstore.swagger.io/v2/swagger.json',
            dataNode: 'default',
          }, //   dataNode 为swagger文档存放数据的节点，一般取值: default | 200
          { source: 'swagger.net.json', dataNode: '200' }, // 想要指定swagger/json/  swagger.net.json的dataNode为 200
        ],
        formatData: (data, { source, dataNode, path }) => {
          // 可省略，默认转换为{code: 200,   message: '成功', data}
          return {
            code: 200,
            message: '成功',
            data,
          }
        },
      },
    ],
  ],
}

最后请将下列文件添加到.gitignore

src/shared/api/apiList.js
src/shared/api/index.js
mock/swagger.js

将下列文件添加到.eslintignore

src/shared/api/index.js

例子

• 请参照本项目example目录

License

MIT