# 8.ApiDoc

官网：https://apidocjs.com/

安装与使用
进阶使用
Mock数据

# 安装与使用

npm install -g apidoc

创建demo.js

/**
 * @api {get} /get Request User information
 * @apiName GetUser Hello APIDoc
 * @apiGroup User
 * @apiVersion 0.2.0
 */

1
2
3
4
5
6

就可以使用apidoc快速形成文档了。

# 进阶使用

接口的进阶定义：

参数地址：https://apidocjs.com/#params

   /**
    * @api {get} /get Request User information
    * @apiName GetUser Hello APIDoc
    * @apiGroup User
    * @apiVersion 0.2.0
    *
    * @apiParam {String} name User's name.
    *
    * @apiSuccess {Object} data data from server.
    * @apiSuccess {Number} code  status of server.
    * @apiSuccess {String} msg  status of server.
    *
    * @apiSuccessExample {json} Success-Response:
    *
    * HTTP/1.1 200 OK
    * {
    *   "firstname": "itheima",
    *   "lastname": "Very Good"
    * }
    *
    * @apiErrorExample {json} Error-Response:
    *
    * HTTP/1.1 500 OK
    * {
    *   "code": 500,
    *   "error": "Server error"
    * }
    */

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

apidoc的配置文件apidoc.json

   {
     "name": "apidoc-example",
     "version": "0.1.0",
     "description": "apidoc example project",
     "title": "Custom apiDoc browser title",
     "url": "https://api.example.com",
     "sampleUrl": "http://127.0.0.1:3000"
   }

1
2
3
4
5
6
7
8

历史接口的变更对比，在apidoc的根目录下创建_apidoc.json即可：

   // 保留接口的历史数据的
   
   /**
    * @api {get} /get Request User information
    * @apiName GetUser Hello APIDoc
    * @apiGroup User
    * @apiVersion 0.1.0
    *
    * @apiParam {String} name User's name.
    *
    * @apiSuccess {Object} data data from server.
    * @apiSuccess {Number} code  status of server.
    * @apiSuccess {String} msg  status of server.
    *
    * @apiSuccessExample {json} Success-Response:
    *
    * HTTP/1.1 200 OK
    * {
    *   "firstname": "John",
    *   "lastname": "Doe"
    * }
    *
    * @apiErrorExample {json} Error-Response:
    *
    * HTTP/1.1 500 OK
    * {
    *   "code": 500,
    *   "error": "Server error"
    * }
    */

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Mock数据

# mockjs

# 安装

第一种：

# 安装
npm install mockjs

1
2

第二种使用CDN：

https://cdnjs.cloudflare.com/ajax/libs/Mock.js/1.0.0/mock.js

直接在Header部分引用即可。

示例：

// 使用 Mock
var Mock = require('mockjs')
var data = Mock.mock({
    // 属性 list 的值是一个数组，其中含有 1 到 10 个元素
    'list|1-10': [{
        // 属性 id 是一个自增数，起始值为 1，每次增 1
        'id|+1': 1
    }]
})
// 输出结果
console.log(JSON.stringify(data, null, 4))

1
2
3
4
5
6
7
8
9
10
11

# 语法

数据模板定义规范 DTD

   # 格式
   
   // 属性名   name
   // 生成规则 rule
   // 属性值   value
   'name|rule': value

1
2
3
4
5
6

注意：

属性名 和 生成规则 之间用竖线 | 分隔。
生成规则 是可选的。
生成规则

有 7 种格式：
1. 'name|min-max': value
2. 'name|count': value
3. 'name|min-max.dmin-dmax': value
4. 'name|min-max.dcount': value
5. 'name|count.dmin-dmax': value
6. 'name|count.dcount': value
7. 'name|+step': value
*生成规则* 的含义需要依赖 *属性值的类型* 才能确定。
属性值 中可以含有 @占位符。
属性值 还指定了最终值的初始值和类型。

示例：

const Mock = require("mockjs");

const params = 2;
const key = "lists|" + params;

const result = Mock.mock({
  code: 200,
  [key]: [
    {
      "number1|1-100.1-10": 1,
      "number2|10.1-10": 1,
      "number3|11.3": 1000,
      "number4|123.10": 1.123,
      "id|+1": 1
    }
  ],
  msg: "mock msg"
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

数据占位符定义规范

   # 格式
   
   @占位符
   @占位符(参数 [, 参数])

1
2
3
4

# 常规应用

Demo1:

在HTML中直接使用script标签引用mockjs
在页面中拦截ajax请求

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Document</title>
    <script src="https://cdn.staticfile.org/Mock.js/1.0.0/mock-min.js"></script>
    <script src="https://cdn.staticfile.org/jquery/3.4.1/jquery.min.js"></script>
  </head>
  <body>
    <div id="app"></div>
    <script>
      Mock.mock(/^\/lists/, "get", {
        code: 200,
        data: {
          "lists|1-10": [
            {
              "id|+1": 0
            }
          ]
        }
      });
      $.ajax({
        url: "/api/lists",
        type: "get",
        dataType: "json",
        success: function(data) {
          if (data.code === 200) {
            var obj = data.data;
            var elem = "";
            $.each(obj.lists, function(item) {
              elem += "<div>" + item + "</div>";
            });
            $("#app").append(elem);
          }
        }
      });
    </script>
  </body>
</html>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

Demo2:

在Vue工程化项目中进行引用：

Mock.js

// 拦截请求
import Mock from "mockjs";

Mock.mock(/\/get/, {
  code: 200,
  "data|10": [
    {
      "id|+1": 1,
      name: "@cname",
      email: "@email",
      picture: "@image('120x120', '#dcdcdc')",
      remark: "@title",
      address: "@city(true)",
      "gender|0-1": 0,
      hobby: "@hobby"
    }
  ]
});

export default Mock;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

在Main.js中进行引用

if (process.env.NODE_ENV !== "production") require("@/mock/index");

← 7.Swagger ui 9.Json-server →