{"id":17728,"library":"jsdoc-http-plugin","title":"JSDoc HTTP Plugin","description":"The JSDoc HTTP Plugin extends JSDoc's core functionality by introducing custom tags specifically designed for documenting HTTP endpoints in JavaScript projects. It is currently at version 0.3.2 and appears to be in a maintenance state, having been forked from an unmaintained project to continue its development. The plugin integrates seamlessly with the default JSDoc template, allowing developers to add structured documentation for API routes, including HTTP verbs, paths, and authentication requirements, using tags like `@path` and `@auth`. This differentiation makes it a valuable tool for projects that require comprehensive API documentation generated directly from source code comments, particularly for RESTful services built with frameworks like Express. The project's last publish was 6 years ago, suggesting a slow release cadence, primarily focused on stability and compatibility with JSDoc itself.","status":"maintenance","version":"0.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/vmarchaud/jsdoc-http-plugin","tags":["javascript","jsdoc","documentation","express","restful","rest","route","plugin"],"install":[{"cmd":"npm install jsdoc-http-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add jsdoc-http-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsdoc-http-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; this package is a plugin for JSDoc and requires it to function.","package":"jsdoc","optional":false}],"imports":[{"note":"This package is a JSDoc plugin and is enabled by adding its name as a string to the `plugins` array in your JSDoc configuration file (e.g., `jsdoc.conf.json`). It is not directly imported or required in application code.","wrong":"import 'jsdoc-http-plugin'; // Not a code import","symbol":"jsdoc-http-plugin","correct":"{ \"plugins\": [\"jsdoc-http-plugin\"] } // in jsdoc.conf"},{"note":"The `@path` tag is a custom JSDoc tag provided by this plugin to define the HTTP verb and route path for an endpoint. It works in conjunction with `@name` to provide a clear description in the generated documentation.","wrong":"/**\n * @route {POST} /v1/file\n */ // @path is the correct tag","symbol":"@path","correct":"/**\n * @path {POST} /v1/file\n */"},{"note":"The `@auth` tag allows documenting the authentication requirements for an HTTP endpoint, with its content appearing under an 'Authentication' sub-heading in the generated documentation.","symbol":"@auth","correct":"/**\n * @auth This route requires API Key authentication.\n */"}],"quickstart":{"code":"npm install jsdoc --save-dev\nnpm install jsdoc-http-plugin --save-dev\n\n// jsdoc.conf.json\n// Place this file in your project root or specify its path when running JSDoc.\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-http-plugin\"],\n    \"templates\": {\n        \"cleverLinks\": false,\n        \"monospaceLinks\": false\n    },\n    \"opts\": {\n      \"recurse\": true\n    }\n}\n\n// example.js\n/**\n * Upload a file to the server.\n *\n * @name File Upload Endpoint\n * @path {POST} /api/v1/file\n * @auth This route requires a valid API key in the 'Authorization' header.\n * @header {string} Authorization - Bearer token for authentication.\n * @param {object} req.body - The request body containing file data.\n * @param {string} req.body.fileName - The name of the file to upload.\n * @param {string} req.body.fileContent - Base64 encoded content of the file.\n * @returns {object} 200 - A success message and the uploaded file's ID.\n * @returns {object} 400 - Bad request if file data is missing or invalid.\n * @returns {object} 401 - Unauthorized if API key is missing or invalid.\n */\nfunction uploadFile(req, res) {\n  // Implementation details for file upload\n  res.status(200).json({ message: 'File uploaded successfully', id: 'some-id' });\n}\n\n// To generate documentation, run:\n// jsdoc --config jsdoc.conf.json example.js -d out/\n// Then open out/index.html in your browser.\n","lang":"javascript","description":"This quickstart demonstrates how to install the JSDoc HTTP plugin, configure it in `jsdoc.conf.json`, and use the `@path`, `@auth`, and `@header` tags to document a simple HTTP POST endpoint in an `example.js` file. It then shows the command to generate the HTML documentation."},"warnings":[{"fix":"Modify your `jsdoc.conf` file to place the markdown plugin first: `\"plugins\": [\"plugins/markdown\", \"jsdoc-http-plugin\"]`.","message":"When using `jsdoc-http-plugin` alongside other JSDoc plugins, particularly the Markdown plugin, ensure that `plugins/markdown` is listed *before* `jsdoc-http-plugin` in your `jsdoc.conf` plugins array to avoid formatting conflicts.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Review the GitHub repository and npm page for recent activity and compatibility notes before integrating into critical projects. Consider alternative API documentation solutions if long-term, high-velocity maintenance is a strict requirement.","message":"This project is a fork of an unmaintained `jsdoc-route-plugin`. While currently maintained, its future development and compatibility with newer JSDoc versions might be less predictable compared to officially supported JSDoc features or more actively developed plugins.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your project's `jsdoc` dependency aligns with the `jsdoc-http-plugin`'s peer dependency range. If upgrading JSDoc to a major new version, thoroughly test plugin functionality or check for a newer version of `jsdoc-http-plugin` that explicitly supports the new JSDoc major version.","message":"JSDoc itself has undergone significant changes in major versions (e.g., JSDoc 4.0.0 dropped `taffydb` and updated Node.js requirements). While `jsdoc-http-plugin`'s peer dependency `jsdoc: ^3.4.3` suggests it's tied to JSDoc 3.x, direct compatibility with JSDoc 4.x or later cannot be assumed without explicit testing or updates to the plugin.","severity":"breaking","affected_versions":"<=0.3.2"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Add `\"jsdoc-http-plugin\"` to the `plugins` array in your `jsdoc.conf.json` file. Ensure the plugin package is installed: `npm install jsdoc-http-plugin --save-dev`.","cause":"The `jsdoc-http-plugin` is not correctly enabled in the JSDoc configuration.","error":"JSDoc: Unknown tag \"@path\""},{"fix":"Verify that your `jsdoc.conf.json` `source.include` and `source.includePattern` options correctly cover the files where your HTTP endpoints are documented. Also, ensure each `@path` tag is preceded by a `@name` tag for JSDoc to properly recognize and render the documentation entry.","cause":"JSDoc might not be configured to scan the files containing your route documentation, or the `@name` tag required by the plugin for proper indexing is missing.","error":"HTTP endpoint documentation is missing or incomplete in generated output."},{"fix":"Adjust the order of plugins in your `jsdoc.conf` file to ensure the Markdown plugin is processed first: `\"plugins\": [\"plugins/markdown\", \"jsdoc-http-plugin\"]`.","cause":"The JSDoc Markdown plugin might be loading after `jsdoc-http-plugin`, causing conflicts in how comment blocks are parsed.","error":"Markdown formatting within @path, @auth, or other HTTP plugin tags is not rendered correctly."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}