{"_id":"@deepglint/egg-swagger-doc-feat","_rev":"4-e4b9abfa58a618b0b10ed2444fd33e4a","name":"@deepglint/egg-swagger-doc-feat","dist-tags":{"latest":"2.2.12"},"versions":{"2.2.12":{"name":"@deepglint/egg-swagger-doc-feat","version":"2.2.12","description":"swagger for egg","eggPlugin":{"name":"swaggerdoc"},"keywords":["egg","eggPlugin","egg-plugin"],"dependencies":{"koa-static-cache":"^5.1.2"},"devDependencies":{"autod":"^3.0.0","autod-egg":"^1.0.0","egg":"^2.0.0","egg-bin":"^4.11.0","egg-ci":"^1.8.0","egg-mock":"^3.13.0","eslint":"^4.19.1","eslint-config-egg":"^5.1.0","webstorm-disable-index":"^1.2.0"},"engines":{"node":">=8.0.0"},"scripts":{"test":"npm run lint -- --fix && egg-bin pkgfiles && npm run test-local","test-local":"egg-bin test","cov":"egg-bin cov","lint":"eslint .","ci":"egg-bin pkgfiles --check && npm run lint && npm run cov","pkgfiles":"egg-bin pkgfiles","autod":"autod"},"ci":{"version":"8, 9"},"repository":{"type":"git","url":"git+https://github.com/DG-Wangtao/egg-swagger-doc.git"},"bugs":{"url":"https://github.com/DG-Wangtao/egg-swagger-doc/issues"},"homepage":"https://github.com/DG-Wangtao/egg-swagger-doc#readme","author":{"name":"yanshijie, wayland, jasine"},"license":"MIT","main":".autod.conf.js","directories":{"lib":"lib","test":"test"},"gitHead":"a89bcb62908b579890e2057fc4861a4b3f5a8b3c","_id":"@deepglint/egg-swagger-doc-feat@2.2.12","_npmVersion":"6.4.1","_nodeVersion":"10.13.0","_npmUser":{"name":"wayland","email":"torwayland@gmail.com"},"dist":{"integrity":"sha512-tyTiLAnMRBW7DaJ2IwMliFSgk84r9b9QPJSfjYelo7Q5SHfYmE0pavt7aIgx8nkeMCGCEgmgFAc8MUfx5od6Tw==","shasum":"9bf2cf339dc35f9233ef4d229fce803a5ca77928","tarball":"https://registry.npmjs.org/@deepglint/egg-swagger-doc-feat/-/egg-swagger-doc-feat-2.2.12.tgz","fileCount":26,"unpackedSize":11470460,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJcr3KmCRA9TVsSAnZWagAAPbYP/108+sOtjx2G8veOODGK\n8NPfvHSJT85LbN2eT6pLx6VvOva61MaotAcL8o1YpoBSnsqWNU+gR3ZWxpg9\nrP6jaNitHJNKyxVGvuYjGgQg68YGSl+5OUocjcIJ7cGYrjvIf/KDzhkxB1QJ\nCmMvsR4F+XQcUof2aCenrtNXGexn7Uz0XI/Se9Az9P4M3bhCbrBX3exMHv30\ngsQ74fewHuQx7WYTuMAWGX0IlNSA5Js3Ruv2eE/1Es5xAMMco6+GRVNIO/fh\nc6TbjpIkLmCH3yU/0Wb/JihFU6Vw/+ycjpOD0q9BbC7tlOSeN5ExdWrAPmYa\nA3GUkXX4WMKBSd9YKLIu+xUBej9X9D7ukWhgNX32FuiBt66V0TlbXn4tB+dI\nLwhRMp/U4dXP9HDvyOJxgdFxqzDJNksXK6Zz5uq+Oe4Hsc1Aqv/awcSl4v1b\n29ikFAZZahjBYX8AUcR4fVykA31VP5j9Ysmi2NqDOo1bo7aUhJMc9tRkv9fL\nnTUFhBov2Btj7ObDwtwNmr1Wzsypdzy0ctEcJjbhVmUWqs5oI5ymi3h8KVh8\nGrsyEjpRwMeUIzrjMsJJOQaSr+YwTkNvAW1faxBVozCM7lkCDg7pNzCr0MIj\nGdHcltNQfzDrTQvGXgkd5BYPK9iCj0+zigZrzCmk4iNSwG9Y7rYj18Dbr7Wq\neT/e\r\n=uHnY\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIAUhj9S53J/nNv8A7XcxQk5Syp4JJ6BCatfCUavhfqp1AiBF23IOGj0AbXJkhsSO8sIWwGB2gFfFkjUOgq8PHPPyUQ=="}]},"maintainers":[{"name":"wayland","email":"torwayland@gmail.com"},{"name":"jasine","email":"jasinechen@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/egg-swagger-doc-feat_2.2.12_1555002021002_0.4857057242255005"},"_hasShrinkwrap":false,"deprecated":"this package has been deprecated"}},"time":{"created":"2019-04-11T17:00:20.827Z","2.2.12":"2019-04-11T17:00:21.268Z","modified":"2022-04-05T03:35:58.589Z"},"maintainers":[],"description":"swagger for egg","homepage":"https://github.com/DG-Wangtao/egg-swagger-doc#readme","keywords":["egg","eggPlugin","egg-plugin"],"repository":{"type":"git","url":"git+https://github.com/DG-Wangtao/egg-swagger-doc.git"},"author":{"name":"yanshijie, wayland, jasine"},"bugs":{"url":"https://github.com/DG-Wangtao/egg-swagger-doc/issues"},"license":"MIT","readme":"# egg-swagger-doc-feat\n\n应用于eggjs的plugin,可自动生成SwaggerUI。应用启动后访问/swaagger-ui.html可以浏览页面，访问/swagger-doc,获取swaggerjson.\n这是一个简单例子，详见[here](https://github.com/Ysj291823/egg-example-api)\n\n## Install\n\n```bash\n$ npm i egg-swagger-doc-feat --save\n```\n\n## Usage\n\n```js\n// {app_root}/config/plugin.js\nexports.swaggerdoc = {\n  enable: true,\n  package: 'egg-swagger-doc-feat',\n};\n```\n\n## Configuration\n\n```js\n// {app_root}/config/config.default.js\nexports.swaggerdoc = {\n  dirScanner: './app/controller',\n  apiInfo: {\n    title: 'egg-swagger',\n    description: 'swagger-ui for egg',\n    version: '1.0.0',\n  },\n  schemes: ['http', 'https'],\n  consumes: ['application/json'],\n  produces: ['application/json'],\n  securityDefinitions: {\n    // apikey: {\n    //   type: 'apiKey',\n    //   name: 'clientkey',\n    //   in: 'header',\n    // },\n    // oauth2: {\n    //   type: 'oauth2',\n    //   tokenUrl: 'http://petstore.swagger.io/oauth/dialog',\n    //   flow: 'password',\n    //   scopes: {\n    //     'write:access_token': 'write access_token',\n    //     'read:access_token': 'read access_token',\n    //   },\n    // },\n  },\n  enableSecurity: false,\n  // enableValidate: true,\n  routerMap: false,\n  enable: true,\n};\n```\n\nsee [config/config.default.js](config/config.default.js) for more detail.\n\n## Introduce\n完成插件引入之后，如果不修改默认配置，应用启动后，会自动扫描app/controller和app/contract下的文件。controller下的文件先不做描述。contract下的文件为定义好的请求体和响应体。\n\n实验性功能：如果routerMap为true,允许自动生成API路由\n\n@Controller\n---\n格式：@Controller {ControllerName}\n\n    a.如果文件第一个注释块中存在标签@Controller，应用会扫描当前文件下的所有注释块，否则扫描将会跳过该文件。\n    b.如果不标示ControllerName，程序会将当前文件的文件名作为ControllerName。\n例：\n```js\n/**\n * @Controller user\n */\nclass UserController extends Controller {\n  //some method\n}\n```\n@Router\n---\n格式：@Router {Mothod} {Path}\n\n    a.Mothod,请求的方法(post/get/put/delete等)，不区分大小写。\n    b.Path,请求的路由。\n\n@Request \n---\n格式：@Request {Position} {Type} {Name} {Description}\n\n    a.position.参数的位置,该值可以是body/path/query/header/formData.\n    b.Type.参数类型，body之外位置目前只支持基础类型,integer/string/boolean/number，及基础类型构成的数组，body中则支持contract中定义的类型。如果position是formData还将支持 file 类型\n    c.Name.参数名称.如果参数名称以*开头则表示必要，否则非必要。\n    d.Description.参数描述\n    c.如果你想给query或者path的参数设置example，你可以在Description前添加以'eg:'开头的参数，实例如下\n    @Request query string contactId eg:200032234567 顾问ID\n\n@Response\n---\n格式：@Response {HttpStatus} {Type} {Description}\n\n    a.HttpStatus.Http状态码。\n    b.Type.同Request中body位置的参数类型。\n    d.Description.响应描述。\n\n@Deprecated\n---\n\n    如果注释块中包含此标识，则表示该注释块注明的接口，未完成或不启用。\n\n@Description\n---\n格式：@Description {Description}\n\n    接口具体描述\n\n@Summary\n---\n格式：@Summary {Summary}\n\n    接口信息小标题\n\n\n例：\n```js\n/**\n * @Controller user\n */\nclass HomeController extends Controller {\n  /**\n   * @Router POST /user\n   * @Request body createUser name description-createUser\n   * @Request header string access_token\n   * @Response 200 baseResponse ok\n   */\n  async index() {\n    this.ctx.body = 'hi, ' + this.app.plugins.swagger.name;\n  }\n```\n如果在config中开启并定义了securityDefinitions,默认enableSecurity为false.则可在注释块中加入@apikey，加入安全验证。也可定义成其他名字，只需@定义好的字段名就好。关于securityDefinitions的定义可以自行搜索。\n\n```js\nexports.swaggerdoc = {\n  securityDefinitions: {\n    apikey: {\n      type: 'apiKey',\n      name: 'clientkey',\n      in: 'header',\n    },\n    // oauth2: {\n    //   type: 'oauth2',\n    //   tokenUrl: 'http://petstore.swagger.io/oauth/dialog',\n    //   flow: 'password',\n    //   scopes: {\n    //     'write:access_token': 'write access_token',\n    //     'read:access_token': 'read access_token',\n    //   },\n    // },\n  },\n  enableSecurity: true,\n};\n```\n## contract定义\n关于Contract的定义其实在测试代码里面，已经把支持的所有情况都定义出来了。详见[here](test/fixtures/apps/swagger-doc-test/app/contract/request/resource.js),这里我简单说明一下，以下是测试代码中的部分contract。\n\n```js\nmodule.exports = {\n  createResource: {\n    resourceId: { type: 'string', required: true, example: '1' },\n    resourceNametrue: { type: 'string', required: true },\n    resourceType: { type: 'string', required: true, enum: ['video', 'game', 'image'] },\n    resourceTag: { type: 'array', itemType: 'string' },\n    owner: { type: 'User', required: true },\n    owners: { type: 'array', itemType: 'User' }\n  },\n};\n```\n@基础类型\n\n\n\n```js\nmodule.exports = {\n  Model名称:{\n    字段名称: { type: 字段类型，required: 字段必要性, example: 示例}\n  }\n}\n```\n注：type可以是array之外的类型，包括自定义的类型，目前自定义类型不支持example\n\n\n---\n@ARRAY\n\n\n```js\nmodule.exports = {\n  Model名称:{\n    字段名称: { type: \"array\"，required: 字段必要性, itemType:数组元素类型}\n  }\n}\n```\ntype为array,itemType为具体的数组元素类型，支持自定义类型。\n\n---\n@自定义类型\n\n关于自定义类型，必须定义在contract目录下，在contract下的其他类型中使用时，直接使用Model名称引入。\n\n---\n@自定义基本类型\n关于自定义基本类型，透传给`egg-validate`的类型，而不需要转为`object`。\n使用方式是这样的：\n\n* 在config.default.js中添加自定义类型（type）或自定义数组元素类型（itemType）的名称\n\n  ```js\n  exports.swaggerdoc = {\n    dirScanner: './app/controller',\n    basePath: '/',\n    apiInfo: {\n      title: 'egg-swagger',\n      description: 'swagger-ui for egg js api',\n      version: '1.0.0',\n    },\n    schemes: ['http', 'https'],\n    consumes: ['application/json'],\n    produces: ['application/json'],\n    enableSecurity: false,\n    routerMap: false,\n    enable: true,\n\n    // 自定义类型\n    type: ['ISOTime’,’enum’],\n    // 自定义数组元素类型\n    itemType: []\n  };\n\n  ```\n\n* 在自己的应用程序中使用 `this.app.validator.addRule`，如：\n\n  ```js\n      this.app.validator.addRule('ISOTime', (rule, value) => {\n        if (!moment(value, moment.ISO_8601).isValid()) {\n          return 'time must be UTC ISO8601 format';\n        }\n      });\n\n  ```\n\n* 在`contract/request`中可以直接使用类型`ISOTime`和`enum`\n\n  ```js\n  module.exports = {\n    custClass: {\n      time: {\n        type: 'ISOTime',\n        required: true,\n        allowEmpty: false\n      },\n\n      dayEnum: {\n        type: 'enum',\n        values: ['mon', 'tue', 'wed', 'thu', 'fri'],\n        default: 'person',\n        required: false,\n        convertType: 'string'\n      }\n    }\n  }\n  ```\n---\n\n因为contract的定义和validate-rule的定义具有极大的相似性，所以目前的版本中定义contract的同时会简单的生成相应的validate-rule.具体的使用'ctx.rule.'加Model名称直接引入。\n\n上面的model，在做验证的时候就可以使用如下的方式(需使用egg-validate)\n```js\n\nctx.validate(ctx.rule.createResource, ctx.request.body);\n\n```\n\n## Questions & Suggestions\n\nPlease open an issue [here](https://github.com/DG-Wangtao/egg-swagger-doc/issues).\nOr Ysj291823's Repo [here](https://github.com/Ysj291823/egg-swagger-doc/issues).\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}