{"_id":"@aspirejo/swagger-generator-express","_rev":"1-b758af6f2d47e8bfaf9ca8cbaa8153b5","name":"@aspirejo/swagger-generator-express","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aspirejo/swagger-generator-express","version":"0.1.0","description":"Swagger document generator for NodeJs express application","main":"index.js","scripts":{"build":"rimraf dist/ && babel ./ --out-dir dist/ --ignore ./node_modules,./.babelrc,./package.json,./npm-debug.log,./docs,./README.md --copy-files","start":"npm run build && node dist/index.js","test":"mocha --require babel-core/register \"./test/**/*.spec.js\"","cover":"istanbul cover ./node_modules/.bin/_mocha -- --require babel-register --recursive"},"repository":{"type":"git","url":"git+https://github.com/AspireJo/swagger-generator-express.git"},"keywords":["Aspire","swagger","documentation","generate","OAI","OpenApi"],"author":{"name":"AspireJo"},"license":"MIT","bugs":{"url":"https://github.com/AspireJo/swagger-generator-express/issues"},"homepage":"https://github.com/AspireJo/swagger-generator-express#readme","devDependencies":{"babel-cli":"^6.26.0","babel-preset-es2015":"^6.24.1","chai":"^4.1.2","eslint":"^4.19.1","eslint-config-airbnb-base":"^12.1.0","eslint-plugin-import":"^2.11.0","istanbul":"^1.1.0-alpha.1","mocha":"^5.1.1","rimraf":"^2.6.2"},"dependencies":{"bluebird":"^3.5.1","glob-promise":"^3.4.0","jsdoc-api":"^4.0.3","lodash":"^4.17.5","yamljs":"^0.3.0"},"gitHead":"d50ab6952951180e5e67c87e6781c3e733afdcb3","_id":"@aspirejo/swagger-generator-express@0.1.0","_npmVersion":"6.0.0","_nodeVersion":"8.11.1","_npmUser":{"name":"yzakarneh","email":"yzakarneh@aspire-services.net"},"dist":{"integrity":"sha512-zPDZ8715PQVtItaDBkAQ7SIYR1zimDBK3YqsxmqGl5EDOlr5h2JA9Fvbzlka0FImjuJFjJPD/s8peIR3KCP8tQ==","shasum":"98799b45b3e9488cdeeee06cf6feee79ce2f56d2","tarball":"https://registry.npmjs.org/@aspirejo/swagger-generator-express/-/swagger-generator-express-0.1.0.tgz","fileCount":92,"unpackedSize":138672,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJa4efdCRA9TVsSAnZWagAA98EP/jzaaVoaGYabdZJmrW5v\nFziF1h7zhP7ZDnv7uVenDCP6rHTlqObCyRAUBMjPnLPBp7IdI0/IUpalQr4v\ntw1ckCafp2FLxOftwdBV67XBUiguV0q65f7fO9r0TODuSrCGbjXcWDkTa2pO\naRHoW/IPoDSmm1J3D0nKeNPvNoQQIPV+zIX7Ufi158tf9MQqkeo4gT7LeQUU\nvAwufpAZOP4y1FQdmxILXSI6YiNvqVyIiTOrz/Jtzl8e4tdLm3OQgdnsG3qC\nuTXPywfGKDvXxEafH6c1cz01pNpKqyiFbCmGYeeRI7lvLuqOV3FrHqCyx77y\nf33tz8mE/fBLOxph71+m7ELN4kwbnUsNnvuxVzKxmN7YzyX+ql6aAvBo9wKs\nW23ZIizwu35bxhQBibDQ3x5CBHbUIZauF5lH0a+65JwrcjVl3kS7X7uFQpYq\nTuqzJx5E071Dlo/hJSKNsQeCSkeMex7xVg181XnZCM+j7fjcZtFTrKjwmeCt\nwknLuXah67/pxdykkTjDDDRsKVoKCuZlkIr5yYKD0kyGlVoIdvSNAtDsSTCV\nJRT2ME58olD+Cb6wDjD40j2araAIoO0eNUEfNBZV4lGaOFkP+uE1l7lRsp5K\nGxB2XChrTPmn4ohgTJ654G7USRb6FEuKE7ZhGoqA0T8MIoTDKcR1gYWHaXaJ\nja8O\r\n=IwSO\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCICLbwyzqsH+9FSa+7QDtDZ0NwXEyf0EEtb5t/QExFzX+AiBCM8GfIfbv7rdFpvI0EON0q1IPZwh0+MUB75+jORX95w=="}]},"maintainers":[{"name":"yzakarneh","email":"yzakarneh@aspire-services.net"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/swagger-generator-express_0.1.0_1524754395838_0.0922703533133502"},"_hasShrinkwrap":false}},"time":{"created":"2018-04-26T14:53:15.781Z","0.1.0":"2018-04-26T14:53:15.909Z","modified":"2022-04-04T15:49:12.049Z"},"maintainers":[{"name":"yzakarneh","email":"yzakarneh@aspire-services.net"}],"description":"Swagger document generator for NodeJs express application","homepage":"https://github.com/AspireJo/swagger-generator-express#readme","keywords":["Aspire","swagger","documentation","generate","OAI","OpenApi"],"repository":{"type":"git","url":"git+https://github.com/AspireJo/swagger-generator-express.git"},"author":{"name":"AspireJo"},"bugs":{"url":"https://github.com/AspireJo/swagger-generator-express/issues"},"license":"MIT","readme":"# swagger-generator-express\n\nReads the `JsDoc` comments and generates `OpenAPI` -`Swagger`- friendly documentation for NodeJs express application.\n\n> for more info visit [jsdoc](http://usejsdoc.org/) & [OpenAPI](https://swagger.io/)\n\n## Prerequisites\n\nThere are three expected types that the generator depends on; **Controller**, **Schema** and **Model**, controllers are the handlers of the request, schemas are the request input structure (and validators), and models are the response object(s). All types are loaded dynamically into the generator based on a configurable pattern.\n\nA controller file name must have a pattern that can be used to identify both method (http) and version from it.\n\n> for more info about schema validations see [express-validator](https://www.npmjs.com/package/express-validator)\n\n## Install\n\n> `npm install @aspirejo/swagger-denerator-express`\n\n## Usage\n\n``` javascript\nimport generator from '@aspirejo/swagger-denerator-express';\ngenerator.generate(config);\n```\n\n``` javascript\nconst generator = require('@aspirejo/swagger-denerator-express');\ngenerator.generate(config);\n```\n\n## Configuration\n\n``` \n- specs\n    |- swagger\n    |- host\n    |- basePath\n    |- schemes\n    |- consumes\n    |- produces\n- baseRoute\n- patterns\n    |- models\n    |- schemas\n    |- controllers\n    |- controllerInfoResolver\n- output\n    |- location\n    |- format\n- tags\n- params\n- versions\n- customResponses\n```\n\n### `specs`\n> required\n\nAn object contains the description of the OpenAPI specifications for the APIs\n|key|type|default value|\n|--|--|--|\n|swagger|`string`|2.0|\n|host|`string`||\n|basePath|`string`|/api/|\n|schemes|`string[]`|[http, https]|\n|consumes|`string[]`|[application/json]|\n|produces|`string[]`|[application/json]|\n\n### `baseRoute`\n> required\n\nA string contains the base route format. MUST contain `{version}` and `{route}` placeholders\n\n### `patterns`\n> required\n\nAn object contains the globbing pattern for models, schemas and controllers, it also specifies the controller name regex that will be used to extract method and version.\n\n|key|type|default value|\n|--|--|--|\n|models|`string`||\n|schemas|`string`||\n|controllers|`string`||\n|controllerInfoResolver|`function`||\n\n**`controllerInfoResolver`**\n\nA function to resolve controller name into a method and a version.\n\nExpected returned object\n``` javascript\n{\n  method\n  version\n}\n```\n\n### `output`\n> required\n\nAn object that defines output settings\n\n|key|type|default value|\n|--|--|--|\n|location|`string`||\n|format|`string`||\n\n> Supported formats are limited to `json` and `yaml` only\n\n### `tags`\n> optional\n\nA list of structured objects that represents all the documentation tags\n\nExpected tag object \n```javascript\n{\n  name\n  description\n}\n```\n\n### `params`\n> optional\n\nA structured object that contains the common parameters definitions.\n\n> Keep in mind that if an endpoint contains a path parameter that is not defined in the doucmentation the swagger (OpenAPI) parser will show an error.\n\n### `versions`\n> optional\n\nA structured object that contains the definition of the parameters that will be applied on all endpoints for that version. Object should be structured as follow:\n\n``` javascript\n{\n  VERSION_NAME:[\n    ARRAY_OF_PARAMETERS_DEFINITIONS\n  ]\n}\n```\n\n### `customResponses`\n> optional\n\nA structured object that contains the reponse result for codes that is not generated by default\n\nDefault response codes \n- 200 : success\n- 400 : bad request\n- 500 : error\n\n### Configurations example\n``` javascript\n{\n  baseRoute: '/{version}/{route}',\n  specs: {\n    host: \"aspire.jo\",\n  },\n  patterns: {\n    controllerInfoResolver: async fileName => {\n      const [, method, version] = /(delete|get|post|put|patch)\\.(v\\d+)(\\.\\S+)*\\.js$/.exec(fileName);\n      return { method, version };\n    },\n    models: `${path.resolve(__dirname, './app/')}/**/models/**/*.js`,\n    schemas: `${path.resolve(__dirname, './app/')}/**/schema/**/*.js`,\n    controllers: `${path.resolve(__dirname, './app/')}/**/controllers/**/_*.js`,\n  },\n  tags: [\n    { name: 'User', description: 'User management endpoints' },\n    { name: 'Cart', description: 'Cart endpoints' }\n  ],\n  output: {\n    location: path.join(__dirname, './documentation/output'),\n    format: 'json'\n  },\n  params: {\n    id: {\n      name: 'id',\n      in: 'path',\n      description: 'Targeted object ID',\n      required: true,\n      type: 'number',\n    },\n  },\n  versions: {\n    v1: [\n      {\n        name: 'Authorization',\n        in: 'header',\n        description: 'Authorization token',\n        required: true,\n        type: 'string',\n      },\n    ],\n  },\n  customResponses: {\n    204: {\n      description: 'No content',\n      schema: {\n        properties: {\n          code: {\n            type: 'number',\n          },\n          message: {\n            type: 'string',\n          },\n        },\n      },\n    },\n    403: {\n      description: 'Unauthorized',\n      schema: {\n        properties: {\n          code: {\n            type: 'number',\n          },\n          message: {\n            type: 'string',\n          },\n        },\n      },\n    }\n  }\n}\n```\n\n## Adding documentation to code\nSee [generator](docs/generator.md)\n\n## Adding new endpoint\nSee [new-endpoint](docs/new-endpoint.md)","readmeFilename":"README.md"}