apidoc使用实践
# 全局设置
package.json中设置：
"scripts": {
"ci": "standard && egg-bin cov",
"doc": "apidoc -i ./app -o public/doc",
"web": "cd web && npm run build",
"fix": "standard --fix && standard",
}
1
2
3
4
5
6
2
3
4
5
6
auth.js
/**
* api 公共类Header Success
*/
/**
* @apiDefine Header
* @apiHeader {String} Authorization jsonwebtoken
*/
/**
* @apiDefine ParamList
* @apiParam (Query) {Number} [page=1] 指定第几页
* @apiParam (Query) {Number} [limit=10] 指定每页的记录数
* @apiParam (Query) {Number} [sort=-1] 是否顺倒序
* @apiParam (Query) {String} [sortBy='updated_at'] 按照排序
* @apiParam (Query) {String} [txt] 搜索
*/
/**
* @apiDefine ResponseList
* @apiSuccess {Number} code 标识码，0表示成功，1表示失败
* @apiSuccess {String} msg 标识信息
* @apiSuccess {Object} data 数据内容
* @apiSuccess {Object[]} data.rows 当前页列表数组
* @apiSuccess {Number} data.count 全部数组个数
* @apiSuccess {Date} timestamp 请求时间
*/
/**
* @apiDefine Success
* @apiSuccess {Number} code 标识码，0表示成功，1表示失败
* @apiSuccess {String} msg 标识信息
* @apiSuccess {Object} data 数据内容
* @apiSuccess {Date} timestamp 请求时间
*/
/**
* 因不能多层继承，直接定义全部的
* @apiDefine Response
*
* @apiSuccess {Number} code 标识码，0表示成功，1表示失败
* @apiSuccess {String} msg 标识信息
* @apiSuccess {Object} data 数据内容
* @apiSuccess {Date} timestamp 请求时间
*
* @apiSuccessExample {json} Response 200 Example
* HTTP/1.1 200 OK
* {
* "code": 200
* "msg": "成功"
* "data": {}
* }
*
* @apiSuccessExample {json} Response 500 Example
* HTTP/1.1 500 Internal Server Error
* {
* "code": 500
* "msg": "xxx"
* }
*
*/
/**
* @apiDefine CODE_200
* @apiSuccessExample {json} Response 200 Example
* HTTP/1.1 200 OK
* {
* "code": 200
* "msg": "成功"
* "data": {}
* "timestamp": 1111111111
* }
*/
/**
* @apiDefine CODE_200_List
* @apiSuccessExample {json} Response 200 Example
* HTTP/1.1 200 OK
* {
* "code": 200
* "msg": "成功"
* "data": {
* "rows":[],
* "count":1,
* }
* "timestamp": 1111111111
* }
*/
/**
* @apiDefine CODE_500
* @apiSuccessExample {json} Response 500 Example
* HTTP/1.1 500 Internal Server Error
* {
* "code": 500
* "msg": "xxx"
* }
*/
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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
# controller处使用
CRUD方法中的示例
'use strict'
const Controller = require('egg').Controller
class Ctrl extends Controller {
constructor (ctx) {
super(ctx)
this.createTransfer = {
host: { type: 'string' }
}
}
/**
* @api {post} routes/ 添加
* @apiDescription 添加
*
* @apiGroup routes
* @apiName create
*
* @apiPermission token
* @apiUse Header
*
* @apiParam (Body) {String} host host
*
* @apiUse Response
*/
async create () {
const {
ctx,
service
} = this
try {
ctx.validate(this.createTransfer)
} catch (error) {
ctx.failure(error, 422)
return
}
const data = ctx.request.body
const res = await service.route.findOneAndCreate(data)
ctx.success(res, 201)
}
/**
* @api {get} routes/ 列表
* @apiDescription 列表
*
* @apiGroup routes
* @apiName index
* @apiPermission token
* @apiUse Header
*
* @apiUse ParamList
* @apiUse ResponseList
*
* @apiUse CODE_200_List
* @apiUse CODE_500
*/
async index () {
const {
ctx,
service
} = this
const res = await service.route.list()
ctx.success(res)
}
/**
* @api {get} routes/:id 详情
* @apiDescription 详情
*
* @apiGroup routes
* @apiName show
*
* @apiPermission token
* @apiUse Header
*
* @apiUse Response
*/
async show () {
const {
ctx,
service
} = this
const query = {
id: ctx.helper.toInt(ctx.params.id)
}
const opts = {}
const res = await service.route.one(query, opts)
ctx.success(res)
}
/**
* @api {put} routes/:id 修改
* @apiDescription 修改
*
* @apiGroup routes
* @apiName update
*
* @apiPermission token
* @apiUse Header
*
* @apiParam (Body) {Number} [status] 状态
* @apiParam (Body) {String} host 地址
*
* @apiUse Response
*/
async update () {
const {
ctx,
service
} = this
const query = {
id: ctx.helper.toInt(ctx.params.id)
}
const {
status, host
} = ctx.request.body
const data = {}
if (status) {
data.status = status
}
if (host) {
data.host = host
}
const model = await service.route.findOrCreate(query, data)
if (!model) {
ctx.throw('model not found', 404)
return
}
ctx.success(model)
}
/**
* @api {delete} routes/:id 删除
* @apiDescription 删除
*
* @apiGroup routes
* @apiName destroy
*
* @apiPermission token
* @apiUse Header
*
* @apiUse Response
*/
async destroy () {
const {
ctx,
service
} = this
const query = ctx.helper.toInt(ctx.params.id)
const model = await service.route.one(query)
if (!model) {
ctx.throw('model not found', 404)
return
}
await model.destroy()
ctx.success(model)
}
}
module.exports = Ctrl
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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
终极常用配置：
{
"title": "接口文档",
"name": "pro",
"version": "0.1.0",
"description": "pro接口文档",
"url": "api/v1/",
"sampleUrl": "http://192.168.11.158:7082/api/v1/",
"template": {
"withCompare": true,
"withGenerator": true
},
"order": [
"users",
"tags",
"products",
"category",
"customer",
"purchase"
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 结合markdown配置使用
apidoc.json
{
"name": "pro",
"version": "0.0.1",
"description": "xx文档",
"title": "xx系统文档",
"sampleUrl": "http://127.0.0.1:3000/api",
"url": "",
"template": {
"withCompare": true,
"withGenerator": true
},
"header": {
"title": "Show you Dog",
"filename": "api_header.md"
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
api_header.md
## 要点说明
- 接口基路径
- http://39.108.58.25x:8xx/api
## 模块说明
- 带【(内部)】开头的，只用于内部使用；
- 其他数据接口，如后面有【Push to Client (example):】也用于设备端推送格式使用
# 更新日志
## [0.2.0] - 2016-09-28
### 变更
* 添加创建会议推送按照议题生成及验证码新功能接口
* 添加查询当前设备在线新接口
### 修复
* 修改设备上报状态类型种类
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
# 参考链接
https://apidocjs.com/
上次更新: 2022/04/15, 05:41:29