egg-swagger2

运营场景

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

安装

npm i egg-swagger2 -S

## 开启插件

javascript

// config/plugin.js
exports.swagger2 = {
  enable: true,
  package: "egg-swagger2",
};

1
2
3
4
5

## 插件配置

config.default.js 中配置

javascript

 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
      }
    },
  };

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

例子

在 /app/router.js 文件中

post 请求

javascript

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",
                },
              },
            },
          },
        },
      },
    },
  });
};

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

get 请求

javascript

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",
            },
          },
        },
      },
    },
  });
};

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