一个带有ui的swagger mocker server
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc
server
ui
.gitignore
README.md
docker-compose.yml

README.md

简介

该项目实现的功能是:根据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. 多文件路由

参考文档: