12.1 运营场景

作为后台,例如有人需要后台提供文档….人家java都有swagger,egg在 egg-swagger2 支持下,我们也可以使用。

12.2 安装

npm i egg-swagger2 -S

12.3 开启插件

1
2
3
4
5
// config/plugin.js
exports.swagger2 = {
enable: true,
package: 'egg-swagger2',
};

12.4 插件配置

config.default.js 中配置

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
config.swagger2 = {
enable: true, // 禁用swagger , 默认为true
base: {
/* default config,support cover
schemes: [
'http',
],
host: '127.0.0.1:7001',
basePath: '/',
consumes: [
'application/json',
],
produces: [
'application/json',
],
*/
info: {
description: '文档介绍,
version: '1.0.0',
title: '文档名称',
contact: {
email: 'caandoll@aliyun.com',
},
license: {
name: 'Apache 2.0',
url: 'http://www.apache.org/licenses/LICENSE-2.0.html',
},
},
tags: [{
name: 'admin',
description: 'Admin desc',
},
{
name: 'role',
description: 'Role desc',
},
],
definitions: {
// model definitions
},
securityDefinitions: {
// security definitions
}
},
};

12.4 例子

在 /app/router.js文件中

12.4.1 post请求

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
module.exports = app => {
const { router, controller, swagger } = app;
router.post('/login', controller.test.postLogin);
swagger.post('/login', {
tags: [
'admin',
],
summary: 'Login a admin',
description: '',
parameters: [
{
in: 'body',
name: 'body',
description: 'admin\'s username & password',
required: true,
schema: {
type: 'object',
required: [ 'username', 'password' ],
properties: {
username: {
type: 'string',
description: 'admin\'s username',
},
password: {
type: 'string',
description: 'admin\'s password',
},
},
},
},
],
responses: {
200: {
description: 'SUCCEED',
schema: {
type: 'object',
properties: {
status: {
type: 'string',
description: 'status',
},
data: {
type: 'object',
description: 'data',
properties: {
token: {
type: 'string',
description: 'token',
},
},
},
},
},
},
},
});
}

12.4.2 get请求

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
module.exports = app => {
const { router, controller, swagger } = app;
router.get('/roles', controller.test.getRoles);
swagger.get('/roles', {
tags: ['role',],
summary: 'search role by page',
description: '',
parameters: [{
in: 'query',
name: 'name',
description: 'role\'s name',
},
{
in: 'query',
name: 'pageIndex',
description: 'pageIndex',
},
{
in: 'query',
name: 'pageSize',
description: 'pageSize',
},
],
responses: {
200: {
description: 'SUCCEED',
schema: {
type: 'object',
properties: {
status: {
type: 'string',
description: 'status',
},
datas: {
type: 'array',
description: 'result datas',
properties: {
token: {
type: 'string',
description: 'token',
},
},
},
pageIndex: {
type: 'number',
description: 'pageIndex',
},
pageSize: {
type: 'number',
description: 'pageSize',
},
totalCount: {
type: 'number',
description: 'totalCount',
},
},
},
},
},
});
}

12.4.3 swagger的使用

npm run dev 跑起来

image.png

获取swgger地址 输入浏览器

你看到就是文档了

image.png

点击try it out

image.png

输入你传的值,然后点击Execute

image.png

结果

image.png

你就可以获取到接口传递过来的值,效果类似postman,但是清晰程度比postman好

12.5 常见问题

一般情况下都不会有问题,但是如果你这时候巧妙的用了egg-static,那么你就会报错了
经过排查,你就会发现

/node_modules/egg-swagger2/app.js

image.png

它会是一个数组,然后报错必须是个字符串,然后你懂得..你给他做成一个字符串即可