Registry / http-networking / jsdoc-http-plugin

jsdoc-http-plugin

library0.3.2jsnpmunverified

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.

http-networking web-framework devops

npm install jsdoc-http-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · JSDOC-HTTP-PLUGIN

jsdoc-http-plugin

http-networkingjavascriptv0.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jsdoc-http-plugin

✓ { "plugins": ["jsdoc-http-plugin"] } // in jsdoc.conf

✗ import 'jsdoc-http-plugin'; // Not a code import

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.

@path

✓ /** * @path {POST} /v1/file */

✗ /** * @route {POST} /v1/file */ // @path is the correct tag

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.

@auth

✓ /** * @auth This route requires API Key authentication. */

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.

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.

npm install jsdoc --save-dev npm install jsdoc-http-plugin --save-dev // jsdoc.conf.json // Place this file in your project root or specify its path when running JSDoc. { "tags": { "allowUnknownTags": true, "dictionaries": ["jsdoc", "closure"] }, "source": { "include": ["."], "exclude": ["node_modules"], "includePattern": ".+\\.js(doc|x)?$", "excludePattern": "(^|\\/|\\\\)_" }, "plugins": ["jsdoc-http-plugin"], "templates": { "cleverLinks": false, "monospaceLinks": false }, "opts": { "recurse": true } } // example.js /** * Upload a file to the server. * * @name File Upload Endpoint * @path {POST} /api/v1/file * @auth This route requires a valid API key in the 'Authorization' header. * @header {string} Authorization - Bearer token for authentication. * @param {object} req.body - The request body containing file data. * @param {string} req.body.fileName - The name of the file to upload. * @param {string} req.body.fileContent - Base64 encoded content of the file. * @returns {object} 200 - A success message and the uploaded file's ID. * @returns {object} 400 - Bad request if file data is missing or invalid. * @returns {object} 401 - Unauthorized if API key is missing or invalid. */ function uploadFile(req, res) { // Implementation details for file upload res.status(200).json({ message: 'File uploaded successfully', id: 'some-id' }); } // To generate documentation, run: // jsdoc --config jsdoc.conf.json example.js -d out/ // Then open out/index.html in your browser.

Debug

Known issues

gotchaWhen 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.

fix

Modify your `jsdoc.conf` file to place the markdown plugin first: `"plugins": ["plugins/markdown", "jsdoc-http-plugin"]`.

affects: >=0.1.0

gotchaThis 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.

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.

affects: >=0.1.0

breakingJSDoc 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.

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.

affects: <=0.3.2

Errors

Common errors & fixes

JSDoc: Unknown tag "@path"

The `jsdoc-http-plugin` is not correctly enabled in the JSDoc configuration.

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`.

HTTP endpoint documentation is missing or incomplete in generated output.

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.

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.

Markdown formatting within @path, @auth, or other HTTP plugin tags is not rendered correctly.

The JSDoc Markdown plugin might be loading after `jsdoc-http-plugin`, causing conflicts in how comment blocks are parsed.

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"]`.

Upgrade

Version history

0.3.2latest on npm

Audit

Dependencies

jsdocrequiredPeer dependency; this package is a plugin for JSDoc and requires it to function.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/vmarchaud/jsdoc-http-plugin ↗

packagehttps://www.npmjs.com/package/jsdoc-http-plugin ↗