{"_id":"swagger-jsdoc-generator","_rev":"10-7f9d748fd904dfb2a1fb248d65572c6c","name":"swagger-jsdoc-generator","time":{"modified":"2022-06-27T02:45:23.418Z","created":"2017-01-07T11:51:20.029Z","1.0.0":"2017-01-07T11:51:20.029Z","1.0.1":"2017-01-07T12:01:04.452Z","1.0.2":"2017-01-07T12:09:21.430Z","1.0.3":"2017-01-07T12:14:50.446Z"},"maintainers":[{"name":"lmammino","email":"lucianomammino@gmail.com"}],"dist-tags":{"latest":"1.0.3"},"description":"Command line script that generates a swagger file based on jsdoc comments","readme":"# swagger-jsdoc-generator\n\n\n[![npm version](https://badge.fury.io/js/swagger-jsdoc-generator.svg)](http://badge.fury.io/js/swagger-jsdoc-generator)\n[![Build Status](https://travis-ci.org/lmammino/swagger-jsdoc-generator.svg?branch=master)](https://travis-ci.org/lmammino/swagger-jsdoc-generator)\n[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)\n\nCommand line script that generates a swagger file based on jsdoc comments.\n\n\n## Usage\n\nYou can use the command as follows\n```bash\nswagger-jsdoc-generator config.js\n```\n\nWhere `config.js` is the path to the configuration file.\n\nIf you don't specify a configuration file the command will look by default\nfor `swaggerJsdoc.config.js` in the current working directory.\n\nThis will print in the standard output a swagger definition in JSON format, so you can easily pipe the output to another command or to a file.\n\nE.g.:\n\n```bash\nswagger-jsdoc-generator config.js | mySwaggerDoc.json\n```\n\nor, assuming you have some utility to convert the definition to HTML, you could do\n\n```bash\nswaggerToHtml < swagger-jsdoc-generator config.js\n```\n\nMore detailed example on how to configure and use the command [later here](https://github.com/lmammino/swagger-jsdoc-generator/blob/master/README.md#example).\n\n\n## Requirements\n\nThis package requires Node.js (version >= 4.0.0) and NPM (version >= 2.14.2).\n\n\n## Install\n\nGlobal install:\n\n```bash\nnpm install --global swagger-jsdoc-generator\n```\n\nAs dev dependency (e.g. if needed as part of a build process):\n\n```bash\nnpm install --save-dev swagger-jsdoc-generator\n```\n\n## Configuration\n\nThe configuration file is used to specify which files needs to be scanned\nto look for jsdoc swagger documentation and other options.\n\nA configuration file can be a plain JSON file or a javascript module\nexporting an object.\n\nAn example of configuration is the following:\n\n```json\n{\n  \"swaggerDefinition\": {\n    \"info\": {\n      \"title\": \"My api\",\n      \"version\": \"1.0.0\",\n    },\n  },\n  \"apis\": [\"src/myApi.js\"]\n}\n```\n\nAll the options supported by [swagger-jsdoc](https://www.npmjs.com/package/swagger-jsdoc) (which is the module used internally by the command)\nare supported.\n\nYou can also [check out an example](https://github.com/lmammino/swagger-jsdoc-generator/blob/master/fixtures/sampleConfig.js) of dynamic configuration through node modules.\n\n\n## Example\n\nHere's a brief example about how to document an API:\n\n```javascript\n// src/mySampleApi.js\n\n/**\n * @swagger\n * /login:\n *   post:\n *     description: Login to the application\n *     produces:\n *       - application/json\n *     parameters:\n *       - name: username\n *         description: Username to use for login.\n *         in: formData\n *         required: true\n *         type: string\n *       - name: password\n *         description: User's password.\n *         in: formData\n *         required: true\n *         type: string\n *     responses:\n *       200:\n *         description: login\n */\napp.post('/login', function(req, res) {\n  res.json(req.body);\n});\n```\n\nThen you need to have `mySampleApi.js` in your `conf.json` configuration file:\n\n```json\n{\n  \"swaggerDefinition\": {\n    \"info\": {\n      \"title\": \"My sample api\",\n      \"version\": \"1.0.0\"\n    }\n  },\n  \"apis\": [\"src/mySampleApi.js\"]\n}\n\n```\n\nFinally you can run the command to produce the swagger definition:\n\n```bash\nswagger-jsdoc-generator conf.json\n```\n\nwhich will produce the following output:\n\n```json\n{\n  \"info\": {\n    \"title\": \"My sample api\",\n    \"version\": \"1.0.0\"\n  },\n  \"swagger\": \"2.0\",\n  \"paths\": {\n    \"/login\": {\n      \"post\": {\n        \"description\": \"Login to the application\",\n        \"produces\": [\n          \"application/json\"\n        ],\n        \"parameters\": [\n          {\n            \"name\": \"username\",\n            \"description\": \"Username to use for login.\",\n            \"in\": \"formData\",\n            \"required\": true,\n            \"type\": \"string\"\n          },\n          {\n            \"name\": \"password\",\n            \"description\": \"User's password.\",\n            \"in\": \"formData\",\n            \"required\": true,\n            \"type\": \"string\"\n          }\n        ],\n        \"responses\": {\n          \"200\": {\n            \"description\": \"login\"\n          }\n        }\n      }\n    }\n  },\n  \"definitions\": {},\n  \"responses\": {},\n  \"parameters\": {},\n  \"securityDefinitions\": {},\n  \"tags\": []\n}\n```\n\n\n## Contributing\n\nEveryone is very welcome to contribute to this project.\nYou can contribute just by submitting bugs or suggesting improvements by\n[opening an issue on GitHub](https://github.com/lmammino/swagger-jsdoc-generator/issues).\n\n\n## License\n\nLicensed under [MIT License](LICENSE). © Luciano Mammino.\n","versions":{"1.0.1":{"name":"swagger-jsdoc-generator","version":"1.0.1","description":"Command line script that generates a swagger file based on jsdoc comments","main":"index.js","bin":{"swagger-jsdoc-generator":"./index.js"},"scripts":{"test":"xo && ava"},"repository":{"type":"git","url":"git+https://github.com/lmammino/swagger-jsdoc-generator.git"},"keywords":["swagger","jsdoc","generator","comments","documentation","api","swagger jsdoc","swagger javascript","swagger documentation"],"author":{"name":"Luciano Mammino"},"license":"MIT","bugs":{"url":"https://github.com/lmammino/swagger-jsdoc-generator/issues"},"homepage":"https://github.com/lmammino/swagger-jsdoc-generator#readme","engines":{"node":">=4","npm":">=2"},"dependencies":{"swagger-jsdoc":"^1.8.4"},"devDependencies":{"ava":"^0.17.0","xo":"^0.17.1"},"xo":{"rules":{"import/no-dynamic-require":0,"indent":[2,2,{"SwitchCase":1}]}},"gitHead":"8b0cf5d1b800e9f0af25acaf5f3894a985296929","_id":"swagger-jsdoc-generator@1.0.1","_shasum":"76f7d21d4e11eb1ef55ebf374fb7fd71363233e6","_from":".","_npmVersion":"2.14.2","_nodeVersion":"4.0.0","_npmUser":{"name":"lmammino","email":"lucianomammino@gmail.com"},"dist":{"shasum":"76f7d21d4e11eb1ef55ebf374fb7fd71363233e6","tarball":"https://registry.npmjs.org/swagger-jsdoc-generator/-/swagger-jsdoc-generator-1.0.1.tgz","integrity":"sha512-oUP7yWBjg74kHX6oV3hELuVp5tsmPYdsJxwCf1XJmSHEPeu6OlLKophrAXUcIvt92xAMbgsY25aayP23KCOkQw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDi99Agle9n0w6vhPvVFhKy3kuLaRgiBqCPEM3IaJmVAwIgdt7/j9HqkSTqjWiUOAP+bvF/Jtr0pz5fFowOAMm5fSs="}]},"maintainers":[{"name":"lmammino","email":"lucianomammino@gmail.com"}],"_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/swagger-jsdoc-generator-1.0.1.tgz_1483790462178_0.1128997269552201"}},"1.0.2":{"name":"swagger-jsdoc-generator","version":"1.0.2","description":"Command line script that generates a swagger file based on jsdoc comments","main":"index.js","bin":{"swagger-jsdoc-generator":"./index.js"},"scripts":{"test":"xo && ava"},"repository":{"type":"git","url":"git+https://github.com/lmammino/swagger-jsdoc-generator.git"},"keywords":["swagger","jsdoc","generator","comments","documentation","api","swagger jsdoc","swagger javascript","swagger documentation"],"author":{"name":"Luciano Mammino"},"license":"MIT","bugs":{"url":"https://github.com/lmammino/swagger-jsdoc-generator/issues"},"homepage":"https://github.com/lmammino/swagger-jsdoc-generator#readme","engines":{"node":">=4","npm":">=2"},"dependencies":{"swagger-jsdoc":"^1.8.4"},"devDependencies":{"ava":"^0.17.0","xo":"^0.17.1"},"xo":{"rules":{"import/no-dynamic-require":0,"indent":[2,2,{"SwitchCase":1}]}},"gitHead":"e2ff2b742ce0ad4eaafb559b57867d64dc4ce7e9","_id":"swagger-jsdoc-generator@1.0.2","_shasum":"51d6e145150477b657d7427ab7d4e180abda91f2","_from":".","_npmVersion":"2.14.2","_nodeVersion":"4.0.0","_npmUser":{"name":"lmammino","email":"lucianomammino@gmail.com"},"dist":{"shasum":"51d6e145150477b657d7427ab7d4e180abda91f2","tarball":"https://registry.npmjs.org/swagger-jsdoc-generator/-/swagger-jsdoc-generator-1.0.2.tgz","integrity":"sha512-EmYlw38Vpd1r1jff1GzpW8h9tvGowqbThZyhbrPn+3T06FCBJ+2nIsLJLE+TdQMpiU5kpGrHREei8RSgmyVk7Q==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCID9Qc2FB8qakirdTT29fUTeaYFiwlghcLhhGlWMQaX7RAiADd1hxlLg9IG9TXgMT2tFSPMh4Ft3YgFinZTvE5YQ0BQ=="}]},"maintainers":[{"name":"lmammino","email":"lucianomammino@gmail.com"}],"_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/swagger-jsdoc-generator-1.0.2.tgz_1483790959380_0.96824910514988"}},"1.0.3":{"name":"swagger-jsdoc-generator","version":"1.0.3","description":"Command line script that generates a swagger file based on jsdoc comments","main":"index.js","bin":{"swagger-jsdoc-generator":"./index.js"},"scripts":{"test":"xo && ava"},"repository":{"type":"git","url":"git+https://github.com/lmammino/swagger-jsdoc-generator.git"},"keywords":["swagger","jsdoc","generator","comments","documentation","api","swagger jsdoc","swagger javascript","swagger documentation"],"author":{"name":"Luciano Mammino"},"license":"MIT","bugs":{"url":"https://github.com/lmammino/swagger-jsdoc-generator/issues"},"homepage":"https://github.com/lmammino/swagger-jsdoc-generator#readme","engines":{"node":">=4","npm":">=2"},"dependencies":{"swagger-jsdoc":"^1.8.4"},"devDependencies":{"ava":"^0.17.0","xo":"^0.17.1"},"xo":{"rules":{"import/no-dynamic-require":0,"indent":[2,2,{"SwitchCase":1}]}},"gitHead":"a77decdd725db46d56fe45887a396b0bc76b40ad","_id":"swagger-jsdoc-generator@1.0.3","_shasum":"cf30cce4ba9a6c05ccf0695a04e90a062967d138","_from":".","_npmVersion":"4.1.1","_nodeVersion":"7.4.0","_npmUser":{"name":"lmammino","email":"lucianomammino@gmail.com"},"dist":{"shasum":"cf30cce4ba9a6c05ccf0695a04e90a062967d138","tarball":"https://registry.npmjs.org/swagger-jsdoc-generator/-/swagger-jsdoc-generator-1.0.3.tgz","integrity":"sha512-48zj65UQ5cWUEB7BgmnTNFKz5LfV/9nKvcTx4OZd1SdRf1QBeVadju0I6k1zr/u1JkSBxpldMhbMhRDFTlXv9w==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCzMrG+c2u+q8QKaCp5czucPB2HeOi0zJxNcx4ak6FpVwIhANZah1VJs49hvPc1WfZfBYMsxFBZudgUCOUkRXWk/o8g"}]},"maintainers":[{"name":"lmammino","email":"lucianomammino@gmail.com"}],"_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/swagger-jsdoc-generator-1.0.3.tgz_1483791288276_0.739430834306404"}}},"homepage":"https://github.com/lmammino/swagger-jsdoc-generator#readme","keywords":["swagger","jsdoc","generator","comments","documentation","api","swagger jsdoc","swagger javascript","swagger documentation"],"repository":{"type":"git","url":"git+https://github.com/lmammino/swagger-jsdoc-generator.git"},"author":{"name":"Luciano Mammino"},"bugs":{"url":"https://github.com/lmammino/swagger-jsdoc-generator/issues"},"license":"MIT","readmeFilename":"README.md","users":{"lmammino":true,"charlie.wilson":true,"mberrang":true}}