- Router
- new Router(options)
- router.mount(Plugin, pluginArgs)
- router.get|put|post|patch|delete|del
- router.routes()
- router.use([path], middleware)
- router.allowedMethods([options])
- router.redirect(source, destination, [code])
- router.route(name)
- router.url(name, params, [options])
- router.param(param, middleware)
- Router.url(path, params)
- Plugin
继承自koa-router，除了prefix选项暂时不支持外，保持其他原功能、特性、性能。在此之外增加一些新功能。
options{object} 路由的配置选项。有以下字段：apiDoc{string}必须api文档或者文档目录。当为api文档目录时，会自动加载目录内的其他文件。apiExplorerVisible{boolean}可选是否启用api-explorer。默认为true。options{object}可选插件的选项，也可以在插件使用时配置。key是插件的名称，value是插件的参数。
apiDoc描述文档可以是yaml或者json格式。当apiDoc是目录时，各个api文档描述目录中的内容将被合并之后加载到OpenAPI协议文档中。/project/paths中的内容将被加载到文档的paths字段下，/project/definitions中的内容将被加载到文档的definitions字段下，其他文件夹不会被加载。
api文档描述目录结构如下：
projectapi.yamlpathsdefinitionsparametersresponsessecurityDefinitionssecuritytagsexternalDocs
如果你只想使用router的基础功能和api-explorer，那么你可以不使用任何插件，�只需要配置apiDoc和apiExplorerVisible即可。服务的路由和业务中间件需要由你手动来绑定。代码如下：
const Koa = require('koa');
const Router = require('koa-oai-router');
const app = new Koa();
const router = new Router({
apiDoc: './api',
apiExplorerVisible: true,
});
// 手动挂载/hello路由与业务中间件
router.get('/hello', (ctx, next) => {
ctx.response.body = 'world';
});
app.use(router.routes());
app.listen(3000);将插件挂载到router上，先挂载的插件先被执行。如果其中一个插件未唤起next()，那么后续插件链的执行将被结束。
Same as koa-router: router.get|put|post|patch|delete|del
Same as koa-router: router.routes()
Same as koa-router: router.use([path], middleware)
Same as koa-router: router.allowedMethods([options])
Same as koa-router: router.redirect(source, destination, [code])
Same as koa-router: router.route(name)
Same as koa-router: router.url(name, params, [options])
Same as koa-router: router.param(param, middleware)
Same as koa-router: Router.url(path, params)
插件是�可以应用在每一个接口上的koa中间。
它的激活取决于该接口描述文档中是否包含它的激活字段(field)。一旦插件被激活，那么handler将在内部被调用，并传入(docOpts)参数，且必须返回一个koa中间件，该中间件将被挂载到当前接口上。
pluginArgs可以在创建router时配置，本方法的配置将拥有最高优先级。
class PluginX extends Plugin {
constructor() {
super();
this.pluginName = 'tags';
this.field = 'tags';
this.after = undefined;
}
handler({ fieldValue }) {
return (ctx, next) => {
// what do you want to do.
};
}
}
// PluginName and Plugin class name both can be config for arguments
const router = new Router({
apiDoc: './api',
options: {
PluginX: pluginArgs,
// OR
tags: pluginArgs
}
});
router.mount(PluginX);pluginArgs也可以在创建插件时配置，本方法的配置将拥有最低的优先级。
class PluginX extends Plugin {
constructor() {
super();
this.pluginName = 'tags';
this.field = 'tags';
this.after = undefined;
}
handler({ fieldValue }) {
return (ctx, next) => {
// what do you want to do.
};
}
}
const router = new Router({
apiDoc: './api',
});
router.mount(plugin, pluginArgs);在构造函数请设置参数：pluginName, field, args。
pluginNamestringoptional插件名称，用于配置插件参数。如果不设置默认使用插件类名称。fieldsstring|string[]required插件的激活字段argsanyoptional插件的参数
在插件初始化时调用，在before之前。插件生命周期中只执行一次，适合做一些插件启动工作。
可选实现
插件的前置业务逻辑，在handler之前执行，
可选实现
docOpts{object} 插件被激活时当前接口文档片段的信息。endpoint{string} 接口的路径field{string} 被激活时的关键字fieldValue{object} 被激活时的关键字对应的数据operation{string} 接口的方法operationValue{object} 接口的描述信息
插件的主要业务逻辑。
必须实现，且要求返回koa中间件，形如：function(ctx, next) {}。
docOpts{object} 插件被激活时当前接口文档片段的信息。endpoint{string} 接口的路径field{string} 被激活时的关键字fieldValue{object} 被激活时的关键字对应的数据operation{string} 接口的方法operationValue{object} 接口的描述信息
插件的后置业务逻辑，在handler之后执行，
可选实现
docOpts{object} 插件被激活时当前接口文档片段的信息。endpoint{string} 接口的路径field{string} 被激活时的关键字fieldValue{object} 被激活时的关键字对应的数据operation{string} 接口的方法operationValue{object} 接口的描述信息