{"id":15963,"library":"apidoc","title":"API Documentation Generator","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/apidoc/apidoc","tags":["javascript","api","apidoc","doc","documentation","rest","restful"],"install":[{"cmd":"npm install apidoc","lang":"bash","label":"npm"},{"cmd":"yarn add apidoc","lang":"bash","label":"yarn"},{"cmd":"pnpm add apidoc","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { createDoc } = require('apidoc')","symbol":"createDoc","correct":"import { createDoc } from 'apidoc'"},{"note":"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.","wrong":"node apidoc -i src/ -o doc/","symbol":"apidoc CLI","correct":"apidoc -i src/ -o doc/"},{"note":"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).","symbol":"ApidocReturn type","correct":"import { createDoc, ApidocReturn } from 'apidoc'"}],"quickstart":{"code":"import path from 'path';\nimport { createDoc } from 'apidoc';\n\n// Resolve paths relative to the current script execution\nconst projectRoot = path.resolve(__dirname, '..'); \n// Using 'example' folder from a cloned apidoc repository for demonstration\nconst srcPath = path.resolve(projectRoot, 'example'); \nconst destPath = path.resolve(projectRoot, 'docs');\n\nconsole.log(`Attempting to generate API documentation from: ${srcPath} to: ${destPath}`);\n\nconst docResult = createDoc({\n  src: srcPath,\n  dest: destPath,\n  // Set dryRun to true to parse and return data without writing files to disk\n  dryRun: false,\n  // Set silent to true to suppress apidoc's console output during generation\n  silent: false,\n  // Optional: Define custom parsing options or template paths here\n});\n\nif (typeof docResult !== 'boolean') {\n  console.log('API documentation generated successfully!');\n  console.log('Parsed API definitions count:', docResult.data.length);\n  console.log('Project information:', docResult.project.name, docResult.project.version);\n} else {\n  console.error('Failed to generate API documentation. Check logs for detailed errors and ensure source paths are correct and comments are well-formed.');\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher. Tools like `nvm` or `volta` can help manage multiple Node.js versions.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure you are using apidoc v1.0.2 or newer. If issues persist, consider simplifying `@apiGroup` names to alphanumeric characters and hyphens.","message":"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.","severity":"gotcha","affected_versions":"<1.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.50.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"apidoc: command not found"},{"fix":"Upgrade your Node.js version to 16 or higher. For example, using nvm: `nvm install 16 && nvm use 16`.","cause":"You are attempting to run apidoc v1.0.0 or later with an unsupported Node.js version, which is now a hard requirement.","error":"Error: Node.js v14 is not supported. Please upgrade to v16 or higher."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'data') or 'project'"},{"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.","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.","error":"The generated API documentation HTML bundle is empty or contains only boilerplate, despite source files having comments."}],"ecosystem":"npm"}