INTRODUCTION

一个swagger文档生成工具，以极简单的方式配置可视化，可测试的API文档。

支持两种配置方式：使用ES7 decorator或使用普通JavaScript对象。

USE

INSTALL

在你的项目中安装它

  $ npm i decorator-doc --save

RUN

在你的项目中使用它

如果使用ES7 decorator语法，你还需要安装Babel插件。使用JavaScript对象定义请参照这里

  $ babel-plugin-transform-decorators-legacy

并在.babelrc中添加这个插件

{
  "plugins": ["transform-decorators-legacy"]
}

然后你就可以运行一下应用了

controller

  const { model, schema, router } = require('decorator-doc')

  @model('Demo model')
  @model.props({
    id: schema('Demo Id').integer('integer').required(),
    name: schema('Demo name').string('string').required(),
    createTime: schema('Demo create time').dateTime()
  })
  class Demo {
    @router('Demo find')
    @router.get('/Demos')
    @router.response.array()
    find(req, res) {

    }
  }

  module.exports = Demo

entry

  const Koa = require('koa')
  const Router = require('koa-router')
  const docGenerator = require('decorator-doc')

  let app = new Koa()
  let router = new Router()

  docGenerator({ router })
  app.use(router.routes())

  app.listen(3000)

NOTE

需要注意的是在使用ES7 decorator语法定义的controller中，每个controller都会被添加一个名为swagger?schema的静态属性，他表示当前controller的Model。

vscode

如果你想让decorator语法高亮不一样，你可以试试在你打开的vscode中添加一个.vscode/settings.json（也可以使用设置面板），复制下面信息，可以修改为你想要高亮颜色

  {
    "editor.tokenColorCustomizations": {
      "textMateRules": [
        {
          "scope": "keyword.operator.decorator.js",
          "settings": {
            "foreground": "#ff0000"
          }
        },
        {
          "name": "class.decorator",
          "scope": "variable.other.readwrite.decorator.js",
          "settings": {
            "foreground": "#89898560"
          }
        },
        {
          "name": "class.decorator.property",
          "scope": "variable.other.property.decorator.js",
          "settings": {
            "foreground": "#89898560"
          }
        }
      ]
    }
  }

如果你使用了代码检测，那么decorator语法可能会显示错误哦，记得在项目中配置.jsconfig.json

  {
    "compilerOptions": {
      "experimentalDecorators": true,
      "emitDecoratorMetadata": true
    }
  }

API DOC

FEATURE

router.join 该方法不能满足一下需求
期望

{
  id: "model id",
  list: [
    {
      id: "other id",
      name: "other name"
    }
  ]
}

因为在join的时候不能在同一个Model拥有相同的属性，所以这里定义时必须使用别名

@router.join('othor', ['id as otherId', 'name'])
@router.response([
  id,
  {
    name: "list",
    description: "list",
    props: ['otherId', 'name']
  }
])

上面的结果就会是

{
  id: "model id",
  list: [
    {
      otherId: "other id",
      name: "other name"
    }
  ]
}