OpenAPI Docs Generator

A powerful CLI tool for automatically generating OpenAPI 3.0 documentation from your JavaScript and TypeScript source code by parsing JSDoc comments and OpenAPI annotations.

Features

• 🚀 Easy to use: Simple CLI interface with intuitive options
• 📝 JSDoc parsing: Extracts OpenAPI documentation from JSDoc comments
• 🎯 Pattern matching: Flexible file pattern matching with glob support
• 🔧 Configurable: Extensive configuration options
• 📤 Multiple formats: Output in JSON or YAML format
• 🚫 Exclude patterns: Skip unwanted files and directories
• 🔍 Debug mode: Detailed logging for troubleshooting
• ⚡ Bootstrap support: Load configuration files and constants

Installation

Global Installation

npm install -g openapi-docs-generator

Local Installation

npm install openapi-docs-generator

Using npx

npx openapi-docs-generator [options] [paths...]

Usage

Basic Usage

# Generate docs for all JS files in src directory
openapi-docs-generator ./src

# Generate docs for TypeScript files
openapi-docs-generator --pattern "*.ts" ./src

# Output to specific file
openapi-docs-generator --output ./docs/openapi.yaml ./src

# Output in JSON format
openapi-docs-generator --format json ./src

Advanced Usage

# Exclude specific directories and files
openapi-docs-generator --exclude node_modules --exclude dist ./src

# Use custom file patterns
openapi-docs-generator --pattern "*/*.ts" --exclude "**/*.test.ts" ./src

# Enable debug mode
openapi-docs-generator --debug ./src

# Load bootstrap files
openapi-docs-generator --bootstrap ./config/constants.js ./src

Command Line Options

Option	Short	Description	Example
--config	-c	Generator configuration	-c operationId.hash=false
--output	-o	Output file path	--output openapi.yaml
--exclude	-e	Exclude paths	--exclude node_modules
--pattern	-n	File pattern to scan	--pattern "*.ts"
--bootstrap	-b	Bootstrap files	--bootstrap config/constants.js
--processor	-p	Additional processors	--processor custom-processor
--format	-f	Output format (json/yaml/auto)	--format json
--debug	-d	Enable debug logging	--debug
--version		OpenAPI version	--version 3.1.0
--help	-h	Show help message	--help

Documentation Annotations

The tool parses JSDoc comments and OpenAPI annotations to generate documentation. Here are some examples:

API Info

/**
 * @OA\Info(
 *   title="My API",
 *   version="1.0.0",
 *   description="A sample API"
 * )
 */

Path Operations

/**
 * @OA\Get(
 *   path="/users",
 *   summary="Get all users",
 *   tags={"users"}
 * )
 */
function getUsers() {
  // Implementation
}

Schema Definitions

/**
 * @OA\Schema(
 *   schema="User",
 *   type="object",
 *   properties={
 *     "id": {"type": "integer"},
 *     "name": {"type": "string"},
 *     "email": {"type": "string", "format": "email"}
 *   }
 * )
 */

Configuration

Config File

You can pass configuration options using the --config flag:

openapi-docs-generator --config operationId.hash=false --config info.title="My API"

Bootstrap Files

Bootstrap files allow you to define constants and configuration that will be loaded before processing:

openapi-docs-generator --bootstrap ./config/api-constants.js ./src

Output Formats

JSON Output

openapi-docs-generator --format json ./src

YAML Output (default)

openapi-docs-generator --format yaml ./src

Auto-detect from file extension

openapi-docs-generator --output ./docs/api.json ./src  # JSON format
openapi-docs-generator --output ./docs/api.yaml ./src  # YAML format

Examples

Generate docs for a Node.js project

openapi-docs-generator \
  --exclude node_modules \
  --exclude dist \
  --pattern "*.js" \
  --output ./docs/openapi.yaml \
  ./src

Generate docs for a TypeScript project

openapi-docs-generator \
  --exclude node_modules \
  --exclude "**/*.test.ts" \
  --pattern "*.ts" \
  --format json \
  --output ./docs/openapi.json \
  ./src

Debug mode with bootstrap

openapi-docs-generator \
  --debug \
  --bootstrap ./config/constants.js \
  --exclude node_modules \
  ./src

API

The tool can also be used programmatically:

const { OpenApiGenerator, Logger } = require('openapi-docs-generator');

const logger = new Logger(true); // Enable debug
const generator = new OpenApiGenerator(logger);

const openapi = generator
  .setVersion('3.0.0')
  .setConfig({ 'operationId.hash': false })
  .generate(['./src/api.js']);

// Output as JSON
console.log(openapi.toJson());

// Output as YAML
console.log(openapi.toYaml());

// Save to file
openapi.saveAs('./docs/openapi.yaml', 'yaml');

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

ISC

Support

If you encounter any issues or have questions, please open an issue on GitHub.