Generating API Documentation: apidoc vs documentation vs jsdoc vs swagger-jsdoc

When building JavaScript applications, keeping API documentation in sync with code is a constant challenge. Writing separate wiki pages or Word docs leads to drift—the code changes, but the docs don't. The solution is to generate documentation directly from source code comments. However, not all generators are built the same. jsdoc, documentation, apidoc, and swagger-jsdoc take very different approaches to this problem. Let's break down how they work, where they shine, and when to avoid them.

📝 Comment Syntax: Standard JSDoc vs Custom Blocks

The first thing you notice is how you write comments. This dictates how easy it is to onboard new developers and whether you can reuse comments for other tools (like IDE tooltips).

jsdoc and documentation both use the industry-standard JSDoc syntax. This is the same syntax your IDE uses to show tooltips when you hover over a function. It's verbose but universally understood.

// jsdoc & documentation syntax
/**
 * Calculates the total price including tax.
 * @param {number} price - The base price.
 * @param {number} taxRate - The tax rate (e.g., 0.2 for 20%).
 * @returns {number} The final total.
 */
function calculateTotal(price, taxRate) {
  return price * (1 + taxRate);
}

apidoc uses its own custom block syntax (@api). It is more concise for REST endpoints but is not recognized by IDEs for type hinting. You effectively write two sets of comments if you want IDE support.

// apidoc syntax
/**
 * @api {post} /orders Create a new order
 * @apiName CreateOrder
 * @apiGroup Orders
 * @apiParam {Number} userId The ID of the user.
 * @apiSuccess {Number} id The new order ID.
 */

swagger-jsdoc also uses standard JSDoc tags, but specifically looks for Swagger/OpenAPI definitions embedded within them. It mixes standard description tags with specific @swagger blocks.

// swagger-jsdoc syntax
/**
 * @swagger
 * /orders:
 *   post:
 *     summary: Create a new order
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               userId:
 *                 type: integer
 */

🏗️ Output Format: Static Sites vs JSON Specs

What you get out of the tool matters just as much as what you put in. Are you building a website? A JSON file for a gateway? A Markdown file for GitHub?

jsdoc generates a traditional, multi-page static HTML website. It includes a navigation sidebar, search index, and detailed class hierarchies. It feels like old-school library docs.

# jsdoc output
# Generates: out/index.html, out/global.html, out/MyClass.html
jsdoc myCode.js -d ./out

documentation is format-agnostic. It can generate HTML, but its superpower is generating Markdown (perfect for README.md) or JSON. This makes it easy to plug into modern static site generators like Gatsby or Next.js.

// documentation usage in a build script
const documentation = require('documentation');

// Generate Markdown
const md = await documentation.build(['src/*.js'], {
  format: 'md',
  shallow: true
});

apidoc generates a single-page application (SPA) style HTML site designed specifically for browsing API endpoints. It includes a built-in "Send Request" button to test APIs directly from the docs.

# apidoc output
# Generates: docs/index.html with interactive "Send" buttons
apidoc -i src/ -o docs/

swagger-jsdoc does not generate HTML. It only produces a swagger.json or yaml file. You must pair this with a separate viewer like Swagger UI or Redoc to actually see the documentation.

// swagger-jsdoc output
const swaggerJsdoc = require('swagger-jsdoc');
const spec = swaggerJsdoc(options);
// spec is a JSON object. Save it to file:
fs.writeFileSync('swagger.json', JSON.stringify(spec));
// Then load swagger.json into Swagger UI separately.

🔌 Ecosystem & Integration

How these tools fit into your wider architecture is a key decision factor.

jsdoc is the grandfather of the group. It works everywhere but feels heavy. It doesn't integrate well with modern bundlers without plugins. It is often seen in older Node.js libraries.

documentation is built for the modern web. It works as a CLI, a Node.js module, or a Gulp/Grunt plugin. Because it outputs JSON/Markdown, it fits easily into CI/CD pipelines that deploy to Netlify or Vercel.

apidoc is a standalone tool. It doesn't care about your build system; you run it, and it spits out HTML. This is simple but can be annoying if you want to customize the theme heavily or inject analytics.

swagger-jsdoc is part of the massive OpenAPI ecosystem. If your company uses microservices, API Gateways, or auto-generates client code (SDKs) for other teams, this is the only choice that fits. The JSON it produces is a standard contract.

🛠️ Real-World Scenarios

Scenario 1: Internal Library for Other Developers

You are building a utility library used by other frontend teams. They need to read docs quickly and see types.

• ✅ Best choice: documentation
• Why? You can generate a clean Markdown file to drop into your GitHub repo, or a sleek HTML site. The JSDoc syntax ensures their IDEs still give them autocomplete.

// Using documentation to update README.md automatically
const docs = await documentation.build(['lib/*.js'], { format: 'md' });
fs.writeFileSync('README.md', docs);

Scenario 2: Public REST API for External Partners

You are exposing a REST API to external customers. They need to test endpoints and see clear request/response examples.

• ✅ Best choice: apidoc
• Why? The generated site has built-in testing capabilities. Partners can try the API right in the browser without setting up Postman.

// apidoc example in controller
/**
 * @api {get} /user/:id Get User Info
 * @apiSuccess {String} name User's full name.
 */
app.get('/user/:id', getUser);

Scenario 3: Enterprise Microservices with Strict Governance

Your organization requires all APIs to follow the OpenAPI standard for security scanning and client generation.

• ✅ Best choice: swagger-jsdoc
• Why? It produces the standard swagger.json required by your API Gateway. You can then plug that JSON into Redoc for a beautiful read-only view.

// swagger-jsdoc definition
const options = {
  definition: {
    openapi: '3.0.0',
    info: { title: 'My API', version: '1.0.0' },
  },
  apis: ['./routes/*.js'],
};
const swaggerSpec = swaggerJsdoc(options);

Scenario 4: Legacy Node.js Module Maintenance

You are taking over an old Node.js project that already has thousands of JSDoc comments.

• ✅ Best choice: jsdoc
• Why? Rewriting all comments to fit apidoc or swagger syntax is too risky. Stick with the tool that already understands the existing comments.

# Running legacy jsdoc
jsdoc -c conf.json -r src/

⚠️ Critical Considerations

The "Double Work" Problem with apidoc

If you choose apidoc, remember that its @api tags are not standard. Your VS Code or WebStorm won't use them for type checking or autocomplete. You might end up writing standard JSDoc for your IDE and apidoc blocks for your docs. This doubles the maintenance burden.

The "Viewer" Requirement for swagger-jsdoc

swagger-jsdoc is not a documentation site generator; it is a definition generator. If you pick this, you must also plan how to host the viewer. Will you use swagger-ui-express in your Node app? Will you host Redoc on S3? This adds an extra step compared to apidoc or jsdoc, which give you HTML immediately.

Maintenance Status

jsdoc is stable but moves very slowly. New ES features sometimes take a long time to be fully supported in its parser. documentation is more active and handles modern JavaScript syntax (like flow types or newer ES6 features) more gracefully. Always check the current issue tracker if you are using cutting-edge syntax.

📊 Summary Table

💡 Final Recommendation

Think about who is reading the docs and what they need to do.

• Building a library for other JS developers? Use documentation. It gives you flexible outputs and plays nice with IDEs.
• Publishing a public REST API for quick consumption? Use apidoc. The built-in "try it out" feature is a huge win for developer experience.
• Working in a regulated enterprise environment? Use swagger-jsdoc. The OpenAPI standard is non-negotiable for tooling integration.
• Stuck on an old project? Stick with jsdoc until you have time to refactor.

Don't overcomplicate it. If you just need a README, documentation is the lightest, most modern path. If you need a full API portal, apidoc or the swagger combo is the way to go.