使用场景

手动编写api文档是一件繁琐的工作，目前npm上有许多文档生成工具，但都是基于注释的， 属于半手动半自动，会存在代码可能都改几版了，文档还没更新的问题。 理想状态应该是代码即文档，代码一改文档同步更新。这也是编写本插件的目的。
它通过定义路由的代码来生成swagger2.0规范的json文件，内嵌swagger ui， 启动项目打开http://localhost:3000/docs 即可看到api文档，也可以将swagger json文档导入到其他支持swagger的文档工具来查看或生成前端接口定义

安装

npm install egg-docer --save

开启插件

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

配置

1// config/config.default.js
2config.docer = {
3      // 是否加载ui，false时不会生成swagger json，也不会注册文档路由
4      enableUI: appInfo.env !== 'prod',
5      // 文档url前缀,生成的swagger json可以通过请求{prefix}/swagger.json获取。
6      prefix: '/docs',
7      // 是否校验输入参数，
8      autoValidate: false,
9      // 校验选项，传递给Joi的校验选项
10      validateOptions: null,
11      // 开启参数校验时，自定义错误处理
12      errorHandler: (err, ctx, next)=>{},
13      // todo schema类型，目前仅支持Joi
14      schemaType: 'joi',
15    }

route

插件会自动加载 app/routes下的文件，使用app.route(options)定义路由,

1  /**
2   * @param {object} options 参数
3   * @param {string} options.method required，http verb
4   * @param {string} options.path required, 接口路径
5   * @param {function|Array<function>} options.handler 处理方法
6   * @param {object} [options.query] query参数schema定义,注意query参数不支持对象嵌套
7   * @param {object} [options.body] body参数schema定义
8   * @param {object} [options.response] 接口输出schema定义，仅用于生成文档，不会对返回值进行校验
9   * @param {string|Array<string>} [options.tags] 接口标签
10   * @param {string} [options.description] 接口描述
11   */

route示例

1// app/routes/user.js
2
3const Joi = require('@hapi/joi');
4module.exports = app => {
5  const { controller } = app;
6
7  const userSchema = Joi.object(
8    {
9      name: Joi.string().max(15).required()
10        .description('用户名'),
11      pds: Joi.string().min(6).description('密码'),
12      age: Joi.number().description('年龄'),
13    }
14  );
15  const prefix = '/api/1/users';
16  const tags = 'users';
17
18  app.route({
19    tags,
20    path: prefix,
21    method: 'post',
22    description: '创建用户',
23    body: userSchema,
24    response: userSchema,
25    handler: controller.user.create,
26  });
27
28  app.route({
29    tags,
30    method: 'get',
31    path: prefix + '/:id',
32    description: '获取指定用户信息',
33    response: userSchema,
34    handler: controller.user.show,
35  });
36
37  app.route({
38    tags,
39    method: 'del',
40    path: prefix + '/:id',
41    description: '删除指定用户',
42    response: userSchema,
43    handler: controller.user.destroy,
44  });
45};

namespace

app.namespace(nsOptions)返回一个namespace对象，可以指定一组路由使用共同的标签，前缀和中间件 namespace对象拥有一个和app.route相同签名的route方法

1/**
2* @param {object} options nsOptions
3* @param {string} options.prefix 前缀
4* @param {string|Array<string>} options.tags 接口标签
5* @param {function|Array<function>} [options.middlewares] 中间就方法或方法数组
6* @return {Namespace} namespace对象
7*/

namespace示例

1// app/routes/book.js
2module.exports = app => {
3  const { controller } = app;
4  const ns = app.namespace({
5    prefix: '/api/1/books',
6    tags: 'books',
7    middlewares: (ctx, next) => {
8      ctx.set('x-use-middlewares', 'true');
9      console.log('book middleware called');
10      next();
11    },
12  });
13
14  const bookSchema = Joi.object({
15    id: Joi.number().integer(),
16    title: Joi.string().max(32).description('名称'),
17    authorName: Joi.string().max(32).description('作者名称'),
18    authorId: Joi.number().description('作者id'),
19    summary: Joi.string().max(255).description('简介'),
20  });
21
22  ns.route({
23    path: '/',
24    method: 'post',
25    description: '创建图书',
26    body: bookSchema,
27    response: bookSchema,
28    handler: controller.book.create,
29  });
30
31  ns.route({
32    path: '/:id',
33    method: 'get',
34    description: '获取指定图书信息',
35    response: bookSchema,
36    handler: controller.book.show,
37  });
38
39
40  ns.route({
41    path: '/:id',
42    method: 'delete',
43    description: '删除图书',
44    response: bookSchema,
45    handler: controller.book.show,
46  });
47
48  ns.route({
49    path: '/:id',
50    method: 'patch',
51    description: '更新图书信息',
52    body: bookSchema,
53    response: bookSchema,
54    handler: controller.book.update,
55  });
56};

context

context.routeOptions指向定义路由时输入的参数

1app.route({
2    tags: 'users',
3    path: '/api/1/users',
4    method: 'post',
5    description: '创建用户',
6    body: userSchema,
7    response: userSchema,
8    handler: ctx=>{
9      console.log(ctx.routeOptions.tags) // users
10      console.log(ctx.routeOptions.body) // userSchema
11    },
12  });

context.getParams():{body, query}用于获取校验返回值，如果autoValidate=fasle则返回原始的输入参数

1// get /api/1/users?page=1&size=20
2const {query} = ctx.getParams();
3console.log(query) // {page:1, size:20}