一个swagger文档生成及验证接口调用的工具,以极简单的方式配置可视化,可测试的API文档。
支持两种配置方式:使用ES7 decorator或使用普通JavaScript对象。
你可以直接参考示例学习使用这个工具。下面进行简单介绍如何使用。
Model的命名必须符合_.upperFirst(_.camelCase(name)),否则也会被转换为这样的模式。
在你的项目中安装它
$ npm i decorator-doc --save
- controllers
required这个文件夹定义Model和API(使用ES7 decorator语法时)以及处理程序。 - config
required这个文件夹下定义服务器配置信息。 - models
optional这个文件夹定义一些Model,如果使用JSON方式配置API和Model信息,则必须有该文件夹。
具体请查看文档中要求。
- USE DECORATOR
// controllers/example.js @model('Example Model') @model.props({ id: Joi.number().description('Example id'), name: Joi.string().description('Example name') }) class Example () { @router('Find example list') @router.get('/examples') @router.join('Page', ['size', 'index', 'count']) @router.response([{ type: 'array', name: 'data', props: ['id', 'name'] }, { type: 'object', name: 'pageInfo', props: ['size', 'index', 'count'] }]) async find (ctx) { ctx.body = { data: [{ id: 1, name: 'Example 1' }], pageInfo: { page: 1, size: 10, count: 1 } } } } module.exports = Example
需要注意的是在使用ES7 decorator语法定义的controller中,每个controller都会被添加一个名为
swagger$$schema的静态属性,他表示当前controller的Model。
- USE JSON
// models/example.js model.exports = { name: 'Example', description: 'Example Model', properties: { id: Joi.number().description('Example id'), name: Joi.string().description('Example name') }, apis: { find: { method: 'GET', path: '/examples', refs: { size: {key: 'size', model: 'Page'}, index: {key: 'index', model: 'Page'}, count: {key: 'count', model: 'Page'} }, response: { type: 'object', props: [{ type: 'array', name: 'data', props: ['id', 'name'] }, { type: 'object', name: 'pageInfo', props: ['size', 'index', 'count'] }] } } } } // controllers/example.js class Example () { async find (ctx) { ctx.body = { data: [{ id: 1, name: 'Example 1' }], pageInfo: { page: 1, size: 10, count: 1 } } } } module.exports = Example
在你的项目中使用它
如果使用ES7 decorator语法,你还需要安装Babel插件。
$ npm i babel-plugin-transform-decorators-legacy --save-dev
并在.babelrc中添加这个插件
{
"plugins": ["transform-decorators-legacy"]
}
如果你想让decorator语法高亮不一样,你可以试试在你打开的vscode中添加一个.vscode/settings.json(也可以使用设置面板),复制下面信息,可以修改为你想要高亮颜色
{
"editor.tokenColorCustomizations": {
"textMateRules": [
{
"scope": "keyword.operator.decorator.js",
"settings": {
"foreground": "#5c6370ff"
},
"comment": "@符号颜色"
},
{
"name": "class.decorator",
"scope": [
"variable.other.readwrite.decorator.js",
"variable.other.property.decorator.js"
],
"comment": "函数部分",
"settings": {
"foreground": "#5c6370ff"
}
},
{
"name": "class.body",
"scope": [
"meta.class.body.js string.quoted.single.js",
"meta.class.body.js constant.other.object.key.js",
"meta.class.body.js string.unquoted.js"
],
"comment": "函数部分参数对象",
"settings": {
"foreground": "#478D3C"
}
},
{
"name": "function.body",
"scope": [
"meta.function.method.js string.quoted.single.js",
"meta.function.method.js constant.other.object.key.js",
"meta.function.method.js string.unquoted.js"
],
"comment": "覆盖上面的在class 方法里面的影响",
"settings": {
"foreground": "#98c379ff"
}
},
{
"name": "function.separator",
"scope": "meta.function.method.js punctuation.separator.key-value.js",
"comment": "覆盖上面的在class 方法里面的影响",
"settings": {
"foreground": "56b6c2ff"
}
}
]
}
}如果你使用了代码检测,那么decorator语法可能会显示错误哦,记得在项目中配置jsconfig.json
{
"compilerOptions": {
"experimentalDecorators": true,
"emitDecoratorMetadata": true
}
}点击查看API文档
-
请求中验证 如果使用了
autoRoute方法将自动验证。 -
写入数据库严重 该步骤使用写入数据与定义的Model验证,如果需要可以使用
joi.validate方法验证,schema为当前controller实例的schema属性。class Model { ... validate (data) { let ret = Joi.validate(data, this.schema) if (ret.error) { throw ret.error } } ... }
这里查看