API Documentation Generator

1.2.0 verified Tue Apr 21 auth: no javascript

apidoc is a command-line utility and programmatic library for generating comprehensive RESTful web API documentation directly from comments embedded within source code. It supports a wide array of programming languages by parsing specialized JSDoc-style comments (e.g., `/** ... */` for JavaScript/Java/C#, `""" ... """` for Python) marked with `@api` tags. The current stable version is 1.2.0, released in February 2024, reflecting a consistent, moderate release cadence focused on stability and feature enhancements. Its key differentiators include a language-agnostic parsing engine that understands various comment styles, a flexible plugin architecture for extending functionality (such as integrating API schemas), and robust programmatic integration options for custom build pipelines. The output is static HTML documentation, making it easy to host and integrate into any project.

Common errors

error apidoc: command not found ↓

cause The `apidoc` CLI tool is not installed globally on your system, or its installation path is not included in your system's PATH environment variable.

fix

Install apidoc globally: npm install -g apidoc or yarn global add apidoc. Verify your npm/yarn global bin directory is correctly set up in your shell's PATH.

error Error: Node.js v14 is not supported. Please upgrade to v16 or higher. ↓

cause You are attempting to run apidoc v1.0.0 or later with an unsupported Node.js version, which is now a hard requirement.

fix

Upgrade your Node.js version to 16 or higher. For example, using nvm: nvm install 16 && nvm use 16.

error TypeError: Cannot read properties of undefined (reading 'data') or 'project' ↓

cause When using `createDoc` programmatically, the function returned `true` (indicating an error occurred) instead of the expected documentation object, often due to parsing issues or misconfiguration.

fix

Always check if typeof docResult !== 'boolean' after calling createDoc. If it's true, an error occurred. Ensure silent: false in your configuration to see console errors, and verify your src directory exists and contains valid @api comments.

error The generated API documentation HTML bundle is empty or contains only boilerplate, despite source files having comments. ↓

cause This can happen if input files are incorrectly filtered, if no valid `@api` comments are found, or in very old versions, due to a bug where the bundle wasn't written.

fix

Double-check your --input (or src) paths and ensure --exclude (or excludeFilters) options are not overly restrictive. Verify your source files contain correctly formatted @api comments. If on an older apidoc version, upgrading to v1.0.0+ resolves a known bundle generation bug.

Warnings

breaking Starting with apidoc v1.0.0, Node.js v16 or newer is explicitly required. Running on older Node.js versions (e.g., v14) will result in execution errors. ↓

fix Upgrade your Node.js environment to version 16 or higher. Tools like `nvm` or `volta` can help manage multiple Node.js versions.

gotcha Prior to apidoc v1.0.0, there was a known issue where the documentation bundle might not be generated into the output directory unless the tool was run with the `--debug` flag. This could lead to seemingly successful runs with empty documentation folders. ↓

fix Upgrade to apidoc v1.0.0 or higher. If upgrading is not immediately possible, try running the CLI with `apidoc -i src/ -o doc/ --debug`.

gotcha Older versions of apidoc (pre-1.0.2) experienced issues with group names containing non-Latin characters or parentheses, which could cause rendering problems, specifically affecting scrollspy navigation. ↓

fix Ensure you are using apidoc v1.0.2 or newer. If issues persist, consider simplifying `@apiGroup` names to alphanumeric characters and hyphens.

gotcha Incorrectly formatted or incomplete JSDoc-style `@api` comments can lead to silent failures, partial documentation, or parsing errors during generation. This is especially common with complex `@apiParam` or `@apiSuccessExample` blocks. ↓

fix Thoroughly review your `@api` comment syntax against the official apidocjs.com documentation. Use the `dryRun: true` option in programmatic usage or the `--debug` flag in CLI mode to get more detailed parsing output and identify syntax errors.

Install

npm install apidoc

yarn add apidoc

pnpm add apidoc

Imports

createDoc
wrong
```
const { createDoc } = require('apidoc')
```
correct
```
import { createDoc } from 'apidoc'
```
apidoc primarily supports ESM for programmatic usage; using CommonJS `require` might lead to import errors or require specific transpilation setups in modern Node.js environments.
apidoc CLI
wrong
```
node apidoc -i src/ -o doc/
```
correct
```
apidoc -i src/ -o doc/
```
The `apidoc` command is typically executed directly after global installation (`npm install -g apidoc`). Invoking it via `node apidoc` is not the standard or recommended approach for the CLI tool.
ApidocReturn type
```
import { createDoc, ApidocReturn } from 'apidoc'
```
For TypeScript users, importing `ApidocReturn` or similar types (available via `@types/apidoc` or bundled types) provides type safety for the object returned by `createDoc` (which contains `data` and `project` properties).

Quickstart

Demonstrates programmatic API documentation generation using `createDoc`, illustrating how to specify source/destination paths, control output, and access the parsed documentation data and project information.

import path from 'path';
import { createDoc } from 'apidoc';

// Resolve paths relative to the current script execution
const projectRoot = path.resolve(__dirname, '..'); 
// Using 'example' folder from a cloned apidoc repository for demonstration
const srcPath = path.resolve(projectRoot, 'example'); 
const destPath = path.resolve(projectRoot, 'docs');

console.log(`Attempting to generate API documentation from: ${srcPath} to: ${destPath}`);

const docResult = createDoc({
  src: srcPath,
  dest: destPath,
  // Set dryRun to true to parse and return data without writing files to disk
  dryRun: false,
  // Set silent to true to suppress apidoc's console output during generation
  silent: false,
  // Optional: Define custom parsing options or template paths here
});

if (typeof docResult !== 'boolean') {
  console.log('API documentation generated successfully!');
  console.log('Parsed API definitions count:', docResult.data.length);
  console.log('Project information:', docResult.project.name, docResult.project.version);
} else {
  console.error('Failed to generate API documentation. Check logs for detailed errors and ensure source paths are correct and comments are well-formed.');
}