{"id":15659208,"url":"https://github.com/lmammino/swagger-jsdoc-generator","last_synced_at":"2025-05-01T14:42:38.216Z","repository":{"id":47333351,"uuid":"78270655","full_name":"lmammino/swagger-jsdoc-generator","owner":"lmammino","description":"Command line script that generates a swagger file based on jsdoc comments","archived":false,"fork":false,"pushed_at":"2021-09-02T20:09:11.000Z","size":110,"stargazers_count":21,"open_issues_count":4,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T21:23:28.901Z","etag":null,"topics":["command","command-line","converter","generator","jsdoc-comments","json","swagger","swagger-jsdoc"],"latest_commit_sha":null,"homepage":"https://lmammino.github.io/swagger-jsdoc-generator/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lmammino.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-07T09:38:11.000Z","updated_at":"2023-11-22T01:15:22.000Z","dependencies_parsed_at":"2022-09-14T05:32:26.832Z","dependency_job_id":null,"html_url":"https://github.com/lmammino/swagger-jsdoc-generator","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmammino%2Fswagger-jsdoc-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmammino%2Fswagger-jsdoc-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmammino%2Fswagger-jsdoc-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmammino%2Fswagger-jsdoc-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lmammino","download_url":"https://codeload.github.com/lmammino/swagger-jsdoc-generator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251892171,"owners_count":21660919,"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":["command","command-line","converter","generator","jsdoc-comments","json","swagger","swagger-jsdoc"],"created_at":"2024-10-03T13:15:35.964Z","updated_at":"2025-05-01T14:42:38.198Z","avatar_url":"https://github.com/lmammino.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"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 \u003c 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 \u003e= 4.0.0) and NPM (version \u003e= 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmammino%2Fswagger-jsdoc-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flmammino%2Fswagger-jsdoc-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmammino%2Fswagger-jsdoc-generator/lists"}