ApiDoc is a RESTful web API Documentation Generator that creates beautiful, interactive documentation from specially formatted comments in source code. It parses API documentation from source files in multiple programming languages and generates static HTML documentation with examples, parameter descriptions, and response formatting.
npm install -g apidoc or npm install apidocconst { createDoc } = require('apidoc');For ES modules:
import { createDoc } from 'apidoc';# Generate documentation from source files
apidoc -i src/ -o doc/
# With configuration file
apidoc -c apidoc.json -i src/ -o doc/
# Watch mode for development
apidoc -i src/ -o doc/ --watchconst { createDoc } = require('apidoc');
const result = createDoc({
src: ['./src'],
dest: './doc',
verbose: true
});
if (result === false) {
console.error('Error generating documentation');
} else if (result === true) {
console.log('Nothing to do');
} else {
console.log('Documentation generated successfully');
}ApiDoc is built around several key components:
Main API for generating documentation from source files. Supports both command-line and programmatic usage with extensive configuration options.
function createDoc(options: ApiDocOptions): boolean | ApiDocResult;
interface ApiDocOptions {
src: string | string[];
dest: string;
template?: string;
config?: string;
verbose?: boolean;
debug?: boolean;
silent?: boolean;
single?: boolean;
dryRun?: boolean;
apiprivate?: boolean;
markdown?: boolean | string;
encoding?: string;
lineEnding?: string;
includeFilters?: string[];
excludeFilters?: string[];
filters?: Record<string, string>;
languages?: Record<string, string>;
parsers?: Record<string, string>;
workers?: Record<string, string>;
copyDefinitions?: boolean;
filterBy?: string;
logFormat?: 'simple' | 'json';
warnError?: boolean;
writeJson?: boolean;
}
interface ApiDocResult {
data: string;
project: string;
}Comprehensive CLI with extensive configuration options for generating documentation from the command line.
// CLI Options
interface CliOptions {
input: string[];
output: string;
config?: string;
template?: string;
verbose?: boolean;
debug?: boolean;
quiet?: boolean;
single?: boolean;
dryRun?: boolean;
private?: boolean;
watch?: boolean;
markdown?: boolean | string;
encoding?: string;
lineEnding?: string;
fileFilters?: string[];
excludeFilters?: string[];
parseFilters?: string[];
parseLanguages?: string[];
parseParsers?: string[];
parseWorkers?: string[];
definitions?: boolean;
filterBy?: string;
logFormat?: 'simple' | 'json';
warnError?: boolean;
writeJson?: boolean;
color?: boolean;
}Internal parsing system and architecture details. These are implementation details not exposed through the public API but helpful for understanding the system.
// Internal functions - NOT part of public API
function parse(options): boolean | ApiDocResult;
function parseSource(source: string, options): ParsedElement[];
function getSpecificationVersion(): string;Configuration file handling and option processing. Supports multiple configuration sources and format validation.
class Reader {
constructor(app: App);
read(): ConfigurationData;
search(): ConfigurationData;
getHeaderFooter(config: ConfigurationData): HeaderFooterData;
}
interface ConfigurationData {
name?: string;
version?: string;
description?: string;
title?: string;
url?: string;
sampleUrl?: string;
input?: string[];
output?: string;
template?: TemplateOptions;
header?: HeaderFooterConfig;
footer?: HeaderFooterConfig;
order?: string[];
}
interface HeaderFooterConfig {
title: string;
filename: string;
}
interface TemplateOptions {
showRequiredLabels?: boolean;
withCompare?: boolean;
withGenerator?: boolean;
aloneDisplay?: boolean;
}Template processing and asset bundling for generating the final HTML documentation. Supports both multi-file and single-file output formats.
class Writer {
constructor(api: ApiDocResult, app: App, cacheBustingQueryParam?: string);
write(): Promise<string>;
createOutputFiles(): Promise<string>;
createSingleFile(): Promise<void>;
}Complete reference for all supported API documentation tags that can be used in source code comments to generate documentation.
// Core tags
@api {method} path [title]
@apiName name
@apiGroup group
@apiVersion version
@apiDescription text
// Parameter tags
@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiQuery [(group)] [{type}] [field=defaultValue] [description]
@apiBody [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
// Response tags
@apiSuccess [(group)] [{type}] field [description]
@apiError [(group)] [{type}] field [description]
// Example tags
@apiExample {type} title
@apiParamExample {type} title
@apiHeaderExample {type} title
@apiSuccessExample {type} title
@apiErrorExample {type} title
// Control tags
@apiPermission name
@apiPrivate
@apiDeprecated [text]
@apiSampleRequest url|off
@apiUse name
@apiDefine name [title]Extension points for custom parsers, workers, filters, and language support. Allows customization of the documentation generation process.
interface App {
addHook(name: string, func: Function, priority?: number): void;
hook(name: string, ...args: any[]): any;
filters: Record<string, string>;
languages: Record<string, string>;
parsers: Record<string, string>;
workers: Record<string, string>;
}