/swagger-mock-server

一个带有ui的swagger mocker server

Primary LanguageJavaScript

简介

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

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

使用说明

安装和运行

项目的部署需要安装docker 和 docker compose, 服务器部署时采用docker compose: docker-compose up -d, 可以直接运行mock server和ui, 然后在7777端口可以看到ui界面,ui里的"Try it out"调用mock server返回假数据.

下面分别介绍ui和mocker server的安装和启动

启动swagger ui

➜  ✗ pwd
/path/to/swagger-mocker-server

➜  ✗ docker-compose up -d swagger_ui

然后访问 http://localhost:7777/

启动 swagger mock server

本地安装依赖和启动(开发时推荐)

# 安装
npm install -g swagger

cd server

npm install

cp swagger-router.js node_modules/swagger-tools/middleware/swagger-router.js

# 启动server (在server目录下运行)
npm run server

# 启动辅助编辑器 开发时方便编辑, 以docker compose启动时, 这个编辑器目前没找到合适的方式暴露出来(主要是 swagger editor难以定制)
npm run edit (在server目录下运行)

用 Docker-compose 方式(搭服务时推荐)

➜  ✗ pwd
/path/to/swagger-mock-server

➜  ✗ docker-compose up -d swagger_mock_server

主要文件目录结构

  • doc : 存放接口文档
  • ui : 根据接口文档生成ui界面方便查看和调用
  • server : 根据文档生成mock接口相关

swagger ui 说明

  • 从doc/swagger.yaml 取文档
  • ui/dist 目录 来源于 swagger-ui 下的dist
  • 修改了swagger/dist中的 index.html 的 SwaggerUIBundle 中的 url, 使其指向doc中的swagger.yaml
  • docker-compose.yaml 中使用 nginx:apline 做基础镜像, 挂载如下对应目录:
ui/dist -> /usr/share/nginx/swagger_ui
doc             -> /usr/share/nginx/doc
swagger.conf    -> /etc/nginx/conf.d/swagger.conf

使得访问容器的7777即可访问ui/dist/index.html, 从而能够解析doc/swagger.yaml

swagger mock server 说明

  • mocker_server 基于 swagger-node 创建
  • 参考 swagger-node 使用 swagger project create 命令创建
  • 采用 "server/swagger-routers.js" 来支持更新灵活的mock语法 相关文档参考 这里
  • 采用 swagger project start -m 的方式来以mock mode的方式启动server 相关文档参考 这里
  • server/Dockerfile 中采用 node:alpine 为基础镜像, 从环境变量获得文档位置 DOCPATH 和 服务监听接口PORT
  • docker-compose.yaml 挂在对应目录 ./doc -> /run/doc

Mock语法说明

先参考 doc/swagger.yaml 中的 x-mock 语法部分, 稍后会补充完整

TODO

    1. 3XX, 4XX, 5XX mock支持
    1. Authentication等
    1. 文件上传下载未测试
    1. 多文件路由

参考文档: