{"id":15091275,"url":"https://github.com/realywithoutname/decorator-doc","last_synced_at":"2025-06-26T00:03:37.205Z","repository":{"id":57211742,"uuid":"101165233","full_name":"realywithoutname/decorator-doc","owner":"realywithoutname","description":"A swagger doc generator with decorator syntax for node.js,It surport use a js object define too.","archived":false,"fork":false,"pushed_at":"2017-10-11T08:14:24.000Z","size":583,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-05-20T08:46:03.742Z","etag":null,"topics":["decorator","documentation-tool","express","nodejs","swagger-specification"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/realywithoutname.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-23T09:54:33.000Z","updated_at":"2023-03-05T06:23:30.000Z","dependencies_parsed_at":"2022-09-07T05:03:01.450Z","dependency_job_id":null,"html_url":"https://github.com/realywithoutname/decorator-doc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/realywithoutname/decorator-doc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realywithoutname%2Fdecorator-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realywithoutname%2Fdecorator-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realywithoutname%2Fdecorator-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realywithoutname%2Fdecorator-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/realywithoutname","download_url":"https://codeload.github.com/realywithoutname/decorator-doc/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realywithoutname%2Fdecorator-doc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261010644,"owners_count":23096773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["decorator","documentation-tool","express","nodejs","swagger-specification"],"created_at":"2024-09-25T10:36:48.408Z","updated_at":"2025-06-26T00:03:37.136Z","avatar_url":"https://github.com/realywithoutname.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swagger your application\n\n## INTRODUCTION\n\n一个[swagger](https://swagger.io)文档生成及验证接口调用的工具，以极简单的方式配置可视化，可测试的API文档。\n\n支持两种配置方式：使用ES7 decorator或使用普通JavaScript对象。\n\n## USE IT\n你可以直接参考[示例](/example)学习使用这个工具。下面进行简单介绍如何使用。\n\n## NOTE\nModel的命名必须符合`_.upperFirst(_.camelCase(name))`,否则也会被转换为这样的模式。\n\n### INSTALL\n在你的项目中安装它\n~~~\n  $ npm i decorator-doc --save\n~~~\n\n### IMPORTANT FOLDER\n- controllers `required` 这个文件夹定义Model和API（使用ES7 decorator语法时）以及处理程序。\n- config `required` 这个文件夹下定义服务器配置信息。\n- models `optional` 这个文件夹定义一些Model，如果使用JSON方式配置API和Model信息，则必须有该文件夹。\n\n\u003e 具体请查看[文档](/API.md#swdobject-config)中要求。\n\n### EXAMPLE\n- USE DECORATOR\n~~~ javascript\n  // controllers/example.js\n  @model('Example Model')\n  @model.props({\n    id: Joi.number().description('Example id'),\n    name: Joi.string().description('Example name')\n  })\n\n  class Example () {\n    @router('Find example list')\n    @router.get('/examples')\n    @router.join('Page', ['size', 'index', 'count'])\n    @router.response([{\n      type: 'array',\n      name: 'data',\n      props: ['id', 'name']\n    }, {\n      type: 'object',\n      name: 'pageInfo',\n      props: ['size', 'index', 'count']\n    }])\n    async find (ctx) {\n      ctx.body = {\n        data: [{\n          id: 1,\n          name: 'Example 1'\n        }],\n        pageInfo: {\n          page: 1,\n          size: 10,\n          count: 1\n        }\n      }\n    }\n  }\n\n  module.exports = Example\n~~~\n\u003e 需要注意的是在使用ES7 decorator语法定义的controller中，每个controller都会被添加一个名为`swagger$$schema`的静态属性，他表示当前controller的Model。\n\n- USE JSON\n\n~~~ javascript\n  // models/example.js\n  model.exports = {\n    name: 'Example',\n    description: 'Example Model',\n    properties: {\n      id: Joi.number().description('Example id'),\n      name: Joi.string().description('Example name')\n    },\n    apis: {\n      find: {\n        method: 'GET',\n        path: '/examples',\n        refs: {\n          size: {key: 'size', model: 'Page'},\n          index: {key: 'index', model: 'Page'},\n          count: {key: 'count', model: 'Page'}\n        },\n        response: {\n          type: 'object',\n          props: [{\n            type: 'array',\n            name: 'data',\n            props: ['id', 'name']\n          }, {\n            type: 'object',\n            name: 'pageInfo',\n            props: ['size', 'index', 'count']\n          }]\n        }\n      }\n    }\n  }\n  // controllers/example.js\n  class Example () {\n    async find (ctx) {\n      ctx.body = {\n        data: [{\n          id: 1,\n          name: 'Example 1'\n        }],\n        pageInfo: {\n          page: 1,\n          size: 10,\n          count: 1\n        }\n      }\n    }\n  }\n\n  module.exports = Example\n~~~\n### RUN\n在你的项目中使用它\n\n如果使用ES7 decorator语法，你还需要安装Babel插件。\n~~~\n  $ npm i babel-plugin-transform-decorators-legacy --save-dev\n~~~\n\n并在.babelrc中添加这个插件\n\n~~~\n{\n  \"plugins\": [\"transform-decorators-legacy\"]\n}\n~~~\n\n### BEAUTY\n\n如果你想让decorator语法高亮不一样，你可以试试在你打开的vscode中添加一个`.vscode/settings.json`（也可以使用设置面板），复制下面信息，可以修改为你想要高亮颜色\n~~~ json\n{\n  \"editor.tokenColorCustomizations\": {\n    \"textMateRules\": [\n      {\n        \"scope\": \"keyword.operator.decorator.js\",\n        \"settings\": {\n          \"foreground\": \"#5c6370ff\"\n        },\n        \"comment\": \"@符号颜色\"\n      },\n      {\n        \"name\": \"class.decorator\",\n        \"scope\": [\n          \"variable.other.readwrite.decorator.js\",\n          \"variable.other.property.decorator.js\"\n        ],\n        \"comment\": \"函数部分\",\n        \"settings\": {\n          \"foreground\": \"#5c6370ff\"\n        }\n      },\n      {\n        \"name\": \"class.body\",\n        \"scope\": [\n        \"meta.class.body.js string.quoted.single.js\",\n          \"meta.class.body.js constant.other.object.key.js\",\n          \"meta.class.body.js string.unquoted.js\"\n        ],\n        \"comment\": \"函数部分参数对象\",\n        \"settings\": {\n          \"foreground\": \"#478D3C\"\n        }\n      },\n      {\n        \"name\": \"function.body\",\n        \"scope\": [\n        \"meta.function.method.js string.quoted.single.js\",\n          \"meta.function.method.js constant.other.object.key.js\",\n          \"meta.function.method.js string.unquoted.js\"\n        ],\n        \"comment\": \"覆盖上面的在class 方法里面的影响\",\n        \"settings\": {\n          \"foreground\": \"#98c379ff\"\n        }\n      },\n      {\n        \"name\": \"function.separator\",\n        \"scope\": \"meta.function.method.js punctuation.separator.key-value.js\",\n        \"comment\": \"覆盖上面的在class 方法里面的影响\",\n        \"settings\": {\n          \"foreground\": \"56b6c2ff\"\n        }\n      }\n    ]\n  }\n}\n~~~\n\n如果你使用了代码检测，那么decorator语法可能会显示错误哦，记得在项目中配置`jsconfig.json`\n~~~ json\n  {\n    \"compilerOptions\": {\n      \"experimentalDecorators\": true,\n      \"emitDecoratorMetadata\": true\n    }\n  }\n~~~\n## API\n点击查看[API文档](/API.md)\n\n## AVLIDATE\n- 请求中验证\n  如果使用了[`autoRoute`](/API.md#autorouteobject-router)方法将自动验证。\n\n- 写入数据库严重\n  该步骤使用写入数据与定义的Model验证，如果需要可以使用`joi.validate`方法验证，`schema`为当前`controller`实例的`schema`属性。\n  ~~~ JavaScript\n    class Model {\n      ...\n      validate (data) {\n        let ret = Joi.validate(data, this.schema)\n        if (ret.error) {\n          throw ret.error\n        }\n      }\n      ...\n    }\n  ~~~\n## FEATURE\n\n[这里](/docs/feature.md)查看\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealywithoutname%2Fdecorator-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frealywithoutname%2Fdecorator-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealywithoutname%2Fdecorator-doc/lists"}