{"_id":"y-egg-swagger-doc","_rev":"2-e7279a113d6ec5135bc3421b30ca2ace","name":"y-egg-swagger-doc","dist-tags":{"latest":"2.3.2"},"versions":{"2.3.2":{"name":"y-egg-swagger-doc","version":"2.3.2","keywords":["egg","eggPlugin","egg-plugin"],"author":{"name":"yanshijie"},"license":"MIT","_id":"y-egg-swagger-doc@2.3.2","maintainers":[{"name":"youngchou1997","email":"1955475274@qq.com"}],"homepage":"https://github.com/Ysj291823/egg-swagger-doc#readme","bugs":{"url":"https://github.com/Ysj291823/egg-swagger-doc/issues"},"ci":{"version":"8, 9"},"dist":{"shasum":"dcf2ab4888d58f1bc34763e6defce4ee1758480c","tarball":"https://registry.npmjs.org/y-egg-swagger-doc/-/y-egg-swagger-doc-2.3.2.tgz","fileCount":26,"integrity":"sha512-Bo5Yf0c1E3ARSXPL2kyhEfFF+WejLkmFhrwUB5KoYdDrliSjXUiztLg18XHkXVJYmLE9vtj0RcEE2teQNmd4sg==","signatures":[{"sig":"MEYCIQDQt09v0ABKdapEhp89CxpY+s8zm0dHNmqd/yOTnzCm4QIhAOmsdhIBGSvFxvMitZwK0/BYj730mv8c7EmfaJ2rbtq5","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":9213259,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJja26WACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmorfg/+MRe5M4pSP8+oQvvWZyElLUv0LZIZr45BtCs0pjdcv3zJy2mV\r\nGga7vD+3vBqEJ2CT9NG2jMFHIBLySe6C+9RkfUCxcxiVqQdYoc6Dmpe/wKM9\r\nvR/4BEcDTtU0lH0yF9494OizEU1SnVy8D4Zmft/JffnbysBYvQRoUhC0LmzO\r\n9OtBPVuObLyxygC8/LAK+QKrABciVvVI6nOIRliaaaXon6d7a5oITrRgGOfZ\r\nfhj2c4rVMF6qnGGU3RXs+aUgWUFessDnXFTYunki0nimubW0t2vuVFE0QAUG\r\nJz86bBBeA9IVF6t0+CcyEm2ZXlSqDwzOr28Qy1ViVDy8R5joXhEAnHQldI2v\r\nomqv9OZahmYcLOb2f4jLvKEeleqeEM4HYUdgEBxqx6u42W1iHSOoULhZv5QE\r\nOPsD81ebTcOSKd+kSGBOcnpPzN0Lod7rcPq11MTa76ANst51S2pIndmTdMQN\r\nK8mYQuRxZVnNHi0vTJB3awAZOGXk9BkBsay9nqup9ocullqnLJ7PhXvEdDHb\r\n80VZqvM8wkEj74bwjKBZJ/VaW+vFxXtS6cMvpMrcS3+jAGZYSMVXOJQekdpb\r\nbgJs5HTQRuk9OezWkBVYnudqbb+A9NoGbxnWpSceYBt4w0K6AyR1KS1KdFIm\r\nhsCMOz7MLNXk9kXLovN1TL3Sl8iXvMalxKk=\r\n=YJES\r\n-----END PGP SIGNATURE-----\r\n"},"engines":{"node":">=8.0.0"},"gitHead":"3bdfe7d01831c252c3e26912e473ea94203ad01c","scripts":{"ci":"egg-bin pkgfiles --check && npm run lint && npm run cov","cov":"egg-bin cov","lint":"eslint .","test":"npm run lint -- --fix && egg-bin pkgfiles && npm run test-local","autod":"autod","pkgfiles":"egg-bin pkgfiles","test-local":"egg-bin test"},"_npmUser":{"name":"youngchou1997","email":"1955475274@qq.com"},"eggPlugin":{"name":"swaggerdoc"},"repository":{"url":"git+https://github.com/Ysj291823/egg-swagger-doc.git","type":"git"},"_npmVersion":"6.14.17","description":"swagger for egg","directories":{},"_nodeVersion":"14.20.1","dependencies":{"koa-static-cache":"^5.1.2"},"_hasShrinkwrap":false,"devDependencies":{"egg":"^2.0.0","autod":"^3.0.0","egg-ci":"^1.8.0","eslint":"^4.11.0","egg-bin":"^4.3.0","egg-mock":"^3.13.0","autod-egg":"^1.0.0","eslint-config-egg":"^5.1.0","webstorm-disable-index":"^1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/y-egg-swagger-doc_2.3.2_1667985046684_0.721463906448143","host":"s3://npm-registry-packages"}}},"time":{"created":"2022-11-09T09:10:46.683Z","modified":"2025-06-17T09:17:05.652Z","2.3.2":"2022-11-09T09:10:46.948Z"},"bugs":{"url":"https://github.com/Ysj291823/egg-swagger-doc/issues"},"author":{"name":"yanshijie"},"license":"MIT","homepage":"https://github.com/Ysj291823/egg-swagger-doc#readme","keywords":["egg","eggPlugin","egg-plugin"],"repository":{"url":"git+https://github.com/Ysj291823/egg-swagger-doc.git","type":"git"},"description":"swagger for egg","maintainers":[{"email":"1955475274@qq.com","name":"xsoul"}],"readme":"# egg-swagger-doc\n\n应用于eggjs的plugin,可自动生成SwaggerUI。应用启动后访问/swaagger-ui.html可以浏览页面，访问/swagger-doc,获取swaggerjson.\n这是一个简单例子，详见[here](https://github.com/Ysj291823/egg-example-api)\n\n特别推荐\n---\n\n如下是taccisum同学开发的一个VSCode代码片段插件，能够自动生成swagger-doc的注释内容，同学们可以下载试试.\n\n项目地址：[https://github.com/taccisum/swagger-doc-snippets](https://github.com/taccisum/swagger-doc-snippets)\n\n因目前还没有发布到插件市场，可以通过\n[https://github.com/taccisum/swagger-doc-snippets/releases](https://github.com/taccisum/swagger-doc-snippets/releases)\n手动安装。\n\n## Install\n\n```bash\n$ npm i egg-swagger-doc --save\n```\n\n## Usage\n\n```js\n// {app_root}/config/plugin.js\nexports.swaggerdoc = {\n  enable: true,\n  package: 'egg-swagger-doc',\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@ENUM\n\n\n```js\nmodule.exports = {\n  Model名称:{\n    字段名称: { type: 字段类型，required: 字段必要性, enum:[]}\n  }\n}\n```\n注: type只能是string或number，enum为具体的数值组成的集合\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因为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/Ysj291823/egg-swagger-doc/issues).\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}