{"_id":"jsdoc-route-plugin","_rev":"5-c877bb801c5f6caf157adc754dddf0d4","name":"jsdoc-route-plugin","description":"Plugin to add custom HTTP Route tags for documenting Express routes.","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"jsdoc-route-plugin","version":"0.1.0","description":"Plugin to add custom HTTP Route tags for documenting Express routes.","main":"index.js","scripts":{"test":"echo 'boo on me I have no tests.'","clean":"rm -rf ./out/*;","example1":"rm -rf ./out/*; ./node_modules/.bin/jsdoc -c ./examples/jsdoc.conf --readme ./examples/README.md; true"},"keywords":["jsdoc","documentation","express","restful","rest","route","plugin"],"engines":{"node":">=4.6.2"},"repository":{"type":"git","url":"git+https://github.com/bvanderlaan/jsdoc-route-plugin.git"},"publishConfig":{"registry":"https://registry.npmjs.org/"},"author":{"name":"Brad van der Laan"},"license":"MIT","devDependencies":{"jsdoc":"^3.4.3"},"gitHead":"c6d7b189d2e171abeed2d61c676225caf4ea0e34","bugs":{"url":"https://github.com/bvanderlaan/jsdoc-route-plugin/issues"},"homepage":"https://github.com/bvanderlaan/jsdoc-route-plugin#readme","_id":"jsdoc-route-plugin@0.1.0","_shasum":"22d167a92b84c11afd570813794a24144a7892e0","_from":".","_npmVersion":"3.10.8","_nodeVersion":"6.9.1","_npmUser":{"name":"bvanderlaan","email":"brad.vanderlaan@gmail.com"},"dist":{"shasum":"22d167a92b84c11afd570813794a24144a7892e0","tarball":"https://registry.npmjs.org/jsdoc-route-plugin/-/jsdoc-route-plugin-0.1.0.tgz","integrity":"sha512-oTsJUsbXy4Y08aNh6uhu7R94v8rv7ScOdgmQgqQlzlG4EeHqWDdRiV177Dh8TE8lzoOLBrXb684RmX5HWqgbyA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIEm0v4nhGCAQAmdFsQPY8MjmeSZ8c9pRK1R2/tnUTypOAiBkqPGZrYf3R6V0ojSVg3+MD6gDLVbgmyFsFh8h9pKA2g=="}]},"maintainers":[{"name":"bvanderlaan","email":"brad.vanderlaan@gmail.com"}],"_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/jsdoc-route-plugin-0.1.0.tgz_1486048976899_0.04275495698675513"}}},"readme":"# JsDoc Route Plugin\n\nThis is a plugin for [JsDoc](http://usejsdoc.org/) which is a tool to generate HTML documentation from comment blocks.\nJsDoc will scan your code files looking for comment blocks then generate a nicely formated HTML document.\n\nJsDoc supports a number of tags to help document a number of things such as each parameter in a function or what the function will return.\nThese tags are picked up by JsDoc and used when generating the HTML documentation; for example function parameters are shown in a table.\n\nThis plugin adds custom tags to JsDoc that work with the default document template. The custom tags are meant to help document Express routes.\n\n## Why JsDoc Route Plugin\n\nI like documenting my code within the code, that way the documentation gets updated as I update the code because the two are co-located.\nI use to do a lot of C++ and C# development and used a tool called [Doxygen](http://doxygen.org) which generated HTML documentation from comment blocks placed around my projects code files.\nWhen I switched over to Node.js development I found [JsDoc](http://usejsdoc.org/) which looks to do the same thing.\n\nMy issue was that I was writing web services which have Express routes and [JsDoc](http://usejsdoc.org/) did not have a nice way to document those.\nI figured out how to fake it by using the `@name` tag but it was hard to document the details about my route; I was writing HTML in the long description to add parameter tables.\n\nTo simplify this I wanted to add custom tags but had a hard time finding instructions on how to do that without modifying the built in [JsDoc](http://usejsdoc.org/) layout template or rolling my own template to use in its sted.\n\nI eventually figured out how to hack it by defining new tags which insert HTML into the description before it gets to the default template; JsDoc Route Plugin is a collection of those tags specifically designed to work with the default [JsDoc](http://usejsdoc.org/) template.\nThey might work with other templates as they just add h5, tables, and paragraphs to the top and/or bottom of the doclets description property.\n\nThey allowed me to document my routes without too much fuss and hopefully if your in the same boat will help you to.\nIf I did this completely the wrong way feel free to let me know what the better solution is but for now install this plugin and start documenting!\n\n## How to install\n\nFirst you need to install JsDoc\n```\nnpm install jsdoc --save-dev\n```\n\nThen you need to install the JsDoc Route Plugin\n\n```\nnpm install jsdoc-route-plugin --save-dev\n```\n\nNext you need to tell [JsDoc](http://usejsdoc.org/) to enable the plugin.\n\nYou can do this by adding a `jsdoc.conf` file and telling [JsDoc](http://usejsdoc.org/) to use it when you run it.\n\n**Example jsdoc.conf**\n```\n{\n    \"tags\": {\n        \"allowUnknownTags\": true,\n        \"dictionaries\": [\"jsdoc\",\"closure\"]\n    },\n    \"source\": {\n        \"include\": [ \".\" ],\n        \"exclude\": [ \"node_modules\" ],\n        \"includePattern\": \".+\\\\.js(doc|x)?$\",\n        \"excludePattern\": \"(^|\\\\/|\\\\\\\\)_\"\n    },\n    \"plugins\": [\"jsdoc-route-plugin\"],\n    \"templates\": {\n        \"cleverLinks\": false,\n        \"monospaceLinks\": false\n    },\n    \"opts\": {\n      \"recurse\": true\n    }\n}\n```\n\nNow run [JsDoc](http://usejsdoc.org/) with the `--config` flag.\n```\n./node_modules/.bin/jsdoc --config jsdoc.conf\n```\n\n## Example\n\nIf you want to see an example of this plugin in action run the `npm run example1` command.\nThat will run [JsDoc](http://usejsdoc.org/) against a sample Express app located in `examples` and produce HTML documentation in the `out` folder.\nTo view the documentation open `out/index.html` in a browser.\n\n## What are the new Tags\n\nThe new tags are all about documenting Express routes.\nFind a list of them and how they are to be used below.\n\n## @route\n\nBecause JsDoc does not know about routes we need to decorate the route documentation with the `@name` tag to make JsDoc think you are documenting a member of the given module.\nThis will add an entry under the **Members** section in the HTML document; however, if we used only the `@name` tag to describe the route verb and path it might look a bit odd as it would show up like this:\n> *(inner)* POST /v1/files\n\nTo make documenting a route a bit nicer I suggest using the `@name` tag to define a common name for the route, such as File Upload, and the `@route` tag to define the verb and route path.\nUsing the `@route` tag will also change the method attribute from *(inner)* to *(route)*.\n\n```\n/**\n * Upload a file.\n *\n * @name File Upload\n * @route {POST} /v1/file\n */\nserver.post({\n  url: '/v1/file',\n}, (req, res, next) => {...}\n```\n\nThe `@route` tag will add a table showing the HTTP verb (i.e. POST, PUT, DEL, GET), and the route path (i.e. /v1/files) for the route you are documenting just under the friendly name of the route above the details section.\nIt would look something similar to the following:\n\n--------------------------------------\n\n## Members\n  *(route)* File Upload\n\n### Route:\n|Method |Path      |\n|:------|:---------|\n| POST  | /v1/file |\n\nUpload a file.\n\n--------------------------------------\n\nOnly one `@route` tag is expected per route document.\n\n## @authentication\n\nThe `@authentication` tag allows you to state what authentication a route requires.\n\n```\n/**\n * Upload a file.\n *\n * @name File Upload\n * @route {POST} /v1/file\n * @authentication This route requires HTTP Basic Authentication. If authentication fails it will return a 401 error.\n */\nserver.post({\n  url: '/v1/file',\n}, (req, res, next) => {...}\n```\n\nIt will result in a new sub-heading called **Authentication** with whatever text you provided to the tag beneath it.\nIt would look something similar to the following:\n\n--------------------------------------\n## Members\n  *(route)* File Upload\n\n### Route:\n|Method |Path      |\n|:------|:---------|\n| POST  | /v1/file |\n\nUpload a file.\n\n### Authentication\nThis route requires HTTP Basic Authentication. If authentication fails it will return a 401 error.\n\n--------------------------------------\n\nOnly one `@authentication` tag is expected per route document.\n\n## @headerparam\n\nThe `@headerparam` allows you to document any parameters which are passed via the header of the HTTP request.\n\nWith this tag you need to provide the name and a description. The name is the first word of the text following the tag.\n* `@headerparam MyName And this part is the description`\n\nYou can also optionally provide a type for the parameter.\n* `@headerparam {String} MyName And this part is the description`\n\n```\n/**\n * Upload a file.\n *\n * @name File Upload\n * @route {POST} /v1/file\n * @headerparam authorization is the identification information for the request\n * @headerparam {String} user-id is the unique User Id to assign to the file\n */\nserver.post({\n  url: '/v1/file',\n}, (req, res, next) => {...}\n```\n\nThe above would add a table under the route description that lists all the header parameters.\nIt would look something similar to the following:\n\n--------------------------------------\n## Members\n  *(route)* File Upload\n\n### Route:\n|Method |Path      |\n|:------|:---------|\n| POST  | /v1/file |\n\nUpload a file.\n\n### Header Parameters:\n|Name            |Type    | Description                                       |\n|:---------------|:-------|:--------------------------------------------------|\n| authorization  |        | is the identification information for the request |\n| user-id        | String | is the unique User Id to assign to the file       |\n\n--------------------------------------\n\nYou can use the `@headerparam` tag as many times as you have parameters in your request header you whish to document.\n\n\n## @bodyparam\n\nThe `@bodyparam` allows you to document any parameters which are passed via the body of the HTTP request.\n\nWith this tag you need to provide the name and a description. The name is the first word of the text following the tag.\n* `@bodyparam MyName And this part is the description`\n\nYou can also optionally provide a type for the parameter.\n* `@bodyparam {String} MyName And this part is the description`\n\nYou can also specify that the parameter is optional by placing the name within square brackets.\n* `@bodyparam {String} [MyName] And this part is the description`\n\nLastly you can define a default value for the parameter. The idea is to document the value which will be used if the parameter is not provided.\n* `@bodyparam {String} [MyName=Phillip] And this part is the description`\n\n\n```\n/**\n * Upload a file.\n *\n * @name File Upload\n * @route {POST} /v1/file\n * @bodyparam {String} userId is the unique identifier for the user we are uploading the file to.\n * @bodyparam {Boolean} [sync=false] when true the route will be synchronous otherwise the route\n * is asynchronous.\n */\nserver.post({\n  url: '/v1/file',\n}, (req, res, next) => {...}\n```\n\nThe above would add a table under the route description that lists all the body parameters.\nIt would look something similar to the following:\n\n--------------------------------------\n## Members\n  *(route)* File Upload\n\n### Route:\n|Method |Path      |\n|:------|:---------|\n| POST  | /v1/file |\n\nUpload a file.\n\n### Body Parameters:\n|Name     |Type     | Attributes | Default | Description                                                                  |\n|:--------|:--------|:-----------|:--------|:-----------------------------------------------------------------------------|\n| userId  | String  |            |         | is the unique identifier for the user we are uploading the file to.          |\n| sync    | Boolean | Optional   | false   | when true the route will be synchronous otherwise the route is asynchronous. |\n\n--------------------------------------\n\nYou can use the `@bodyparam` tag as many times as you have parameters in your request body you whish to document.\n\n## @routeparam\n\nThe `@routeparam` allows you to document any parameters which make up part of the route path.\n\nWith this tag you need to provide the name and a description. The name is the first word of the text following the tag.\n* `@routeparam MyName And this part is the description`\n\nYou can also optionally provide a type for the parameter.\n* `@routeparam {String} MyName And this part is the description`\n\n```\n/**\n * Download a file.\n *\n * @name Download File\n * @route {GET} /v1/files/:fileId\n * @routeparam {String} :fileId is the unique identifier for the file to download.\n */\nserver.get({\n  url: '/v1/files/:fileId',\n}, (req, res, next) => {...}\n```\n\nThe above would add a table under the route description that lists all the route parameters.\nIt would look something similar to the following:\n\n--------------------------------------\n## Members\n  *(route)* Download File\n\n### Route:\n|Method |Path               |\n|:------|:------------------|\n| GET   | /v1/files/:fileId |\n\nDownload a file.\n\n### Route Parameters:\n|Name      |Type    | Description                                        |\n|:---------|:-------|:---------------------------------------------------|\n| :fileId  | String | is the unique identifier for the file to download. |\n\n--------------------------------------\n\nYou can use the `@routeparam` tag as many times as you have parameters in your route path.\n\n## @queryparam\n\nThe `@queryparam` allows you to document any parameters which are passed via HTTP request url.\n\nWith this tag you need to provide the name and a description. The name is the first word of the text following the tag.\n* `@queryparam MyName And this part is the description`\n\nYou can also optionally provide a type for the parameter.\n* `@queryparam {String} MyName And this part is the description`\n\nYou can also specify that the parameter is optional by placing the name within square brackets.\n* `@queryparam {String} [MyName] And this part is the description`\n\nLastly you can define a default value for the parameter. The idea is to document the value which will be used if the parameter is not provided.\n* `@queryparam {String} [MyName=Phillip] And this part is the description`\n\n\n```\n/**\n * Download files.\n *\n * @name Download Files\n * @route {GET} /v1/files\n * @queryparam {String} [fileType] will limit the download to just these file types.\n */\nserver.get({\n  url: '/v1/files',\n}, (req, res, next) => {...}\n```\n\nThe above would add a table under the route description that lists all the query parameters.\nIt would look something similar to the following:\n\n--------------------------------------\n## Members\n  *(route)* Download Files\n\n### Route:\n|Method |Path       |\n|:------|:----------|\n| GET   | /v1/files |\n\nDownload files.\n\n### Query Parameters:\n|Name      |Type    | Attributes | Description                                       |\n|:---------|:-------|:-----------|:--------------------------------------------------|\n| fileType | String | Optional   | will limit the download to just these file types. |\n\n--------------------------------------\n\nYou can use the `@queryparam` tag as many times as you have parameters in your request url you whish to document.\n\n## Donations\n\nIf you like JsDoc Route Plugin and want to support it and other open source work that I do you can do so via [Gratipay](https://gratipay.com/~bvanderlaan/).\n\n[![Support via Gratipay](https://cdn.rawgit.com/gratipay/gratipay-badge/2.3.0/dist/gratipay.svg)](https://gratipay.com/~bvanderlaan/)\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/bvanderlaan/jsdoc-route-plugin. This project is intended to be a safe, welcoming space for\ncollaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe library is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","maintainers":[{"name":"bvanderlaan","email":"brad.vanderlaan@gmail.com"}],"time":{"modified":"2022-06-19T05:57:43.284Z","created":"2017-02-02T15:22:57.140Z","0.1.0":"2017-02-02T15:22:57.140Z"},"homepage":"https://github.com/bvanderlaan/jsdoc-route-plugin#readme","keywords":["jsdoc","documentation","express","restful","rest","route","plugin"],"repository":{"type":"git","url":"git+https://github.com/bvanderlaan/jsdoc-route-plugin.git"},"author":{"name":"Brad van der Laan"},"bugs":{"url":"https://github.com/bvanderlaan/jsdoc-route-plugin/issues"},"license":"MIT","readmeFilename":"README.md","users":{"kwpeters":true}}