# MockDemo

**Repository Path**: zeno/mock-demo

## Basic Information

- **Project Name**: MockDemo
- **Description**: MockDemo
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-03-14
- **Last Updated**: 2021-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于 `express`, `apidoc`, `mockjs` 的接口设计及文档生成

## 概要

在项目开始的初期，一般流程为产品出原形，之后，UI设计、接口设计同步进行，随后前后端同步开始开发。往往此时还没开发完毕的接口，前端在开发过程中需要用到mock api，本项目便应运而生。

## 项目结构

```
mock                    // mock 服务根目录
├── apidoc.json         // apidoc 配置，也可在 package.json 中配置
├── index.js            // mock 服务入口文件
├── public
│   └── apidoc
└── routes              // mock 路由
    ├── index.js        // mock 路由入口文件
    └── user.js         // router user 模块
```

## 环境配置

1. 安装依赖

```bash
# 安装依赖
yarn add --dev express mockjs apidoc
# npm i --save-dev express mockjs apidoc
```

2. 配置 `mock/apidoc.json`

```bash
cp ./node_modules/apidoc/example/apidoc.json ./mock/
```

```json
{
  "name": "工程名称如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取",
  "version": "版本如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取",
  "description": "工程描述如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取",
  "title": "浏览器标题",
  "url": "api路径前缀例如:https://api.github.com/v1",
  "sampleUrl": "如果设置了该参数，那么在文档中便可以看到用于测试接口的一个表单(详情可以查看参数@apiSampleReques)",
  "header": {
    "title": "页眉导航标题",
    "filename": "header.md"
  },
  "footer": {
    "title": "页脚导航标题",
    "filename": "footer.md"
  },
  "order": "接口名称或接口组名称的排序列表如果未定义，那么所有名称会自动排序\"order\": [ \"Error\", \"Define\", \"PostTitleAndError\", PostError\"]",
  "template": {
    "withCompare": true,
    "withGenerator": true,
    "aloneDisplay": false
  }
}
```

3. 在相应api router 编写 `apidoc` 注释 - [apiDoc-Params](https://apidocjs.com/#params)

```js
/**
 * @api {get} /user/:id Get User information
 * @apiVersion 0.1.0
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
```

4. `mock/index.js`

```js
const express = require('express');
const routes = require('./routes');

const app = express();
app.use('/api', routes);                                      // 加载路由
app.use('/public/apidoc', express.static('public/apidoc'))    // 访问apidoc 文档
app.listen(3000);
```

5. 配置 package.json

```json
{
  "scripts": {
    "mock": "cd mock && node index.js",
    "apidoc": "apidoc -i mock -o mock/public/apidoc"
  }
}
```

## 使用

到此就可以开展Api的设计以及文档编写的工作了，后续便可基于mock与后端同步开展工作, mockjs 的用法此处不赘述,  直接查看文档[Mock.Random](https://github.com/nuysoft/Mock/wiki/Mock.Random)