express-route-by-jsdoc

Generate Express routes and OpenAPI documentation directly from JSDoc comment blocks.

Installation

npm install express-route-by-jsdoc

Quick start

const express = require("express");
const routeGenerator = require("express-route-by-jsdoc");

const app = express();
app.use(express.json());

const options = {
  docs: {
    url: "/docs",
    json: "/docs.json",
  },
  swaggerDefinition: {
    info: {
      title: "Example API",
      version: "1.0.0",
      description: "Demo application for express-route-by-jsdoc",
    },
    host: "localhost:3100",
    basePath: "/api/v1",
    schemes: ["http"],
  },
  basedir: __dirname,
  files: ["./routes/*.js"],
};

routeGenerator(app, options);

const port = process.env.PORT || 3100;
app.listen(port, () => {
  console.log(`API ready at http://localhost:${port}`);
  console.log(`Swagger UI at http://localhost:${port}${options.docs.url}`);
});

See examples/basic-server for a runnable sample.

Options

| Option | Type | Description | | ------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | docs | { url: string, json?: string, ui?: object } | Optional Swagger UI mounting point. When provided, the UI is served at url and a JSON spec is exposed at json (defaults to {url}.json). | | swaggerDefinition | object | Base OpenAPI/Swagger definition. Supports legacy host, basePath, and schemes keys or modern openapi + servers. | | basedir | string | Absolute directory used to resolve the glob patterns. | | files | string[] | Glob patterns pointing at the controller files that contain JSDoc annotations. | | api.postprocess | (req, res, next) => void | Optional Express middleware appended after each generated route. Defaults to a wrapper that responds with { response, data }. |

Documenting routes

Annotate each handler with a JSDoc block. The generator looks for the tags below:

/**
 * Retrieve user information based on the supplied user id.
 * @route GET /users/{userid}
 * @group User - Operations about user data
 * @param {string} userid.path.required - user identifier - eg: wisit
 * @returns {object} 200 - Successful response with user payload
 * @returns {Error} default - Unexpected error
 */
module.exports = function getUser(req, res, next) {
  // populate `res.body` with the payload you want to return
  res.body = { id: req.params.userid };
  next();
};

Supported annotations

• @route <METHOD> <path> defines the HTTP verb and relative path. Path parameters wrapped in {} are converted to Express parameters automatically.
• @group <Name> - <description> controls the OpenAPI tag used for the operation.
• @param {Type} name.location[.required] - description produces path/query/header parameters or a JSON request body (when location is body).
• @returns {Type} status - description creates OpenAPI responses. Use default for non-specific status codes.

Response shape

When you do not supply a custom postprocess middleware, the generator replies with:

{
  "response": {
    "result": "true",
    "remark": "success",
    "code": 200
  },
  "data": {
    "...": "your handler payload"
  }
}

Override options.api.postprocess if you prefer a different envelope.

Upgrading from 0.0.4

• Replaced the deprecated express-swagger-generator dependency with swagger-ui-express and a custom OpenAPI generator.
• Swapped out doctrine-file for the actively maintained comment-parser library.
• Added Jest + Supertest coverage, ESLint (flat config), and revamped examples.
• Express 5 is now the default runtime. Ensure your project runs on Node.js 18 or newer.

Contributing

1. Clone the repository and run npm install.
2. Use npm test to execute the Jest suite.
3. Run npm run lint before submitting a pull request.

Issues and pull requests are welcome!