JSDoc HTTP Plugin

0.3.2 verified Thu Apr 23 auth: no javascript maintenance

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.

Common errors

error JSDoc: Unknown tag "@path" ↓

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

error HTTP endpoint documentation is missing or incomplete in generated output. ↓

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.

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.

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

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

Warnings

gotcha 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. ↓

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

gotcha 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. ↓

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.

breaking 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. ↓

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.

Install

npm install jsdoc-http-plugin

yarn add jsdoc-http-plugin

pnpm add jsdoc-http-plugin

Imports

jsdoc-http-plugin
wrong
```
import 'jsdoc-http-plugin'; // Not a code import
```
correct
```
{ "plugins": ["jsdoc-http-plugin"] } // in jsdoc.conf
```
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
wrong
```
/**
 * @route {POST} /v1/file
 */ // @path is the correct tag
```
correct
```
/**
 * @path {POST} /v1/file
 */
```
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.

Quickstart

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.