Command Line Interface

Complete command-line tool for generating API documentation from API Extractor JSON files. Supports multiple output formats including Markdown, YAML for DocFX, and experimental config-driven generation.

Capabilities

Markdown Action

Generates Markdown documentation files from API Extractor JSON files.

api-documenter markdown --input-folder <path> --output-folder <path>

Parameters:

• --input-folder, -i (required): Directory containing *.api.json files from API Extractor
• --output-folder, -o (required): Directory where markdown files will be generated

Usage Example:

# Generate markdown docs
api-documenter markdown --input-folder ./temp --output-folder ./docs

# Using short flags  
api-documenter markdown -i ./temp -o ./docs

YAML Action

Generates YAML documentation files compatible with DocFX and Office Add-ins documentation systems.

api-documenter yaml --input-folder <path> --output-folder <path> [--office] [--new-docfx-namespaces] [--yaml-format <format>]

Parameters:

• --input-folder, -i (required): Directory containing *.api.json files from API Extractor
• --output-folder, -o (required): Directory where YAML files will be generated
• --office (optional): Enable Office Add-ins specific features and formatting
• --new-docfx-namespaces (optional): Enable experimental DocFX namespace support
• --yaml-format (optional): Output format, either 'udp' or 'sdp' (default: 'sdp')

Usage Examples:

# Basic YAML generation
api-documenter yaml --input-folder ./temp --output-folder ./yaml-docs

# Office Add-ins specific YAML
api-documenter yaml -i ./temp -o ./office-docs --office

# DocFX with experimental namespaces
api-documenter yaml -i ./temp -o ./docfx-docs --new-docfx-namespaces

# Specify YAML format
api-documenter yaml -i ./temp -o ./docs --yaml-format udp

Generate Action

Experimental configuration-driven documentation generation that uses a config file to determine output format and options.

api-documenter generate --input-folder <path> --output-folder <path>

Parameters:

• --input-folder, -i (required): Directory containing *.api.json files from API Extractor
• --output-folder, -o (required): Directory where documentation files will be generated

Requirements:

• Must have an api-documenter.json configuration file in the current directory

Usage Example:

# Config-driven generation (requires api-documenter.json)
api-documenter generate --input-folder ./temp --output-folder ./docs

Configuration File

For the generate action, create an api-documenter.json configuration file:

{
  "configFormatVersion": "1.0",
  "outputTargets": [
    {
      "outputFormat": "markdown"
    }
  ],
  "newlineKind": "lf",
  "plugins": [
    {
      "packageName": "my-documenter-plugin",
      "enabled": true
    }
  ],
  "tableOfContents": {
    "catchAllCategory": "Other"
  }
}

Programmatic CLI Usage

import { ApiDocumenterCommandLine } from "@microsoft/api-documenter/lib/cli/ApiDocumenterCommandLine";

const commandLine = new ApiDocumenterCommandLine();
commandLine.executeAsync().catch(console.error);

CLI Classes

ApiDocumenterCommandLine

Main command line parser that orchestrates all available actions.

class ApiDocumenterCommandLine extends CommandLineParser {
  constructor();
}

BaseAction

Abstract base class for all CLI actions providing common functionality including API model loading and folder management.

abstract class BaseAction extends CommandLineAction {
  /**
   * Creates a new BaseAction instance
   * @param options - Command line action configuration options
   */
  protected constructor(options: ICommandLineActionOptions);
  
  /**
   * Builds the API model from input files and validates folders
   * @returns API model with input/output folder paths
   */
  protected buildApiModel(): IBuildApiModelResult;
}

interface IBuildApiModelResult {
  /**
   * The loaded API model containing all packages from *.api.json files
   */
  apiModel: ApiModel;
  
  /**
   * Input folder path containing the *.api.json files
   */
  inputFolder: string;
  
  /**
   * Output folder path where documentation will be written
   */
  outputFolder: string;
}

MarkdownAction

CLI action implementation for markdown documentation generation.

class MarkdownAction extends BaseAction {
  constructor(parser: CommandLineParser);
}

YamlAction

CLI action implementation for YAML documentation generation with DocFX and Office support.

class YamlAction extends BaseAction {
  constructor(parser: CommandLineParser);
}

GenerateAction

Experimental CLI action for config-driven documentation generation.

class GenerateAction extends BaseAction {
  constructor(parser: CommandLineParser);
}

Error Handling

The CLI tool provides detailed error messages for common issues:

• Missing input folder: Clear message when API Extractor files are not found
• Configuration errors: Detailed validation messages for malformed config files
• Plugin loading errors: Specific error information when plugins fail to load
• File system errors: Informative messages for permission and disk space issues

All CLI actions return appropriate exit codes (0 for success, non-zero for errors) for use in build scripts and CI/CD pipelines.