Appearance

Commerce Engine Documentation Generator ​

A production-ready Python replacement for the Node.js extract-complete-docs.cjs script. This tool generates identical documentation with better maintainability, configurability, and extensibility.

Status: ✅ Production Ready - Direct replacement for Node.js script

Features ​

  • ✨ Universal OpenAPI Support: Works with any OpenAPI 3.x specification (JSON or YAML)
  • 🔗 TypeScript Integration: Enhanced documentation with TypeScript type definitions
  • 📱 SDK Integration: Automatic extraction of SDK methods and examples from source code
  • 📚 Multiple Output Formats: Markdown, HTML, JSON (extensible)
  • 🔄 Cross-References: Automatic linking between components and operations
  • 🎯 Configurable: Highly customizable via configuration files or CLI arguments
  • 🚀 Fast: Efficient processing with caching and parallel operations

Quick Start ​

Installation ​

bash
cd packages/docs/scripts/python
pip install -r requirements.txt

Basic Usage ​

bash
# Generate docs from URL
python -m openapi_doc_generator --openapi-url https://api.example.com/openapi.json --output-dir ./docs

# Generate docs from local file with TypeScript integration
python -m openapi_doc_generator \
  --openapi-file ./api-spec.json \
  --typescript-file ./types.d.ts \
  --output-dir ./docs \
  --verbose

# Generate docs with SDK integration
python -m openapi_doc_generator \
  --config config.example.yaml

Commerce Engine Production Usage ​

Replace the Node.js script with the Python version:

bash
# Using the convenience script (recommended)
./generate-docs.sh

# Or directly with Python
python3 -m openapi_doc_generator --config config.commerce-engine.yaml

# With verbose output
./generate-docs.sh --verbose

Configuration ​

The tool supports both command-line arguments and configuration files (YAML/JSON).

Configuration File Example ​

yaml
# Input Sources
openapi_url: "https://api.example.com/openapi.json"
typescript_types_file: "./types/api.d.ts"

# Output Configuration
output_dir: "./generated-docs"
output_format: "markdown"
clean_output_dir: true

# SDK Integration
sdks:
  - name: "main"
    lib_path: "./src/lib"
    client_pattern: "extends APIClient"

# Documentation Options
generate_indexes: true
generate_cross_references: true
include_examples: true
include_typescript_definitions: true
include_openapi_schemas: true

# General Options
verbose: true

Create Sample Configuration ​

bash
python -m openapi_doc_generator --create-config config.yaml

Architecture ​

The tool is designed with a modular architecture:

openapi_doc_generator/
├── __init__.py          # Package exports
├── config.py            # Configuration management
├── openapi_parser.py    # OpenAPI specification parsing
├── doc_generator.py     # Documentation file generation
├── sdk_mapper.py        # SDK method extraction and mapping
├── cli.py              # Command-line interface
└── __main__.py         # Module entry point

Key Components ​

  • OpenAPIParser: Handles fetching, parsing, and extracting data from OpenAPI specifications
  • SDKMapper: Extracts method information from SDK source files and maps them to API operations
  • DocumentationGenerator: Creates markdown files with cross-references and examples
  • Config: Manages configuration from files and CLI arguments

SDK Integration ​

The tool can automatically extract SDK methods and their JSDoc examples from source code:

Supported Patterns ​

  • Client Classes: Automatically detects client classes extending base API clients
  • Method Extraction: Parses public async methods with Promise<ApiResult<T>> return types
  • JSDoc Examples: Extracts @example sections from method comments
  • Parameter Parsing: Handles complex TypeScript parameter types

Example SDK Method ​

typescript
/**
 * Authenticate user with email and password
 * 
 * @example
 * ```typescript
 * const result = await sdk.auth.login({
 *   email: "[email protected]",
 *   password: "secure-password"
 * });
 * 
 * if (result.success) {
 *   console.log("Login successful:", result.data.user);
 * }
 * ```
 */
public async login(params: LoginParams): Promise<ApiResult<LoginResponse>> {
  return this.client.post("/auth/login", params);
}

This method would be automatically mapped to the POST /auth/login operation and the example would be included in the generated documentation.

Output Structure ​

The generated documentation follows a structured layout:

docs/
├── index.md              # Main index
├── sdk/
│   ├── index.md         # SDK overview
│   ├── storefront.md    # Storefront SDK methods
│   └── pos.md           # POS SDK methods
├── schemas/
│   ├── index.md         # Schemas index
│   └── *.md             # Individual schemas
├── operations/
│   ├── index.md         # Operations index
│   └── *.md             # Individual operations
├── responses/
│   ├── index.md         # Responses index
│   └── *.md             # Individual responses
├── parameters/
│   ├── index.md         # Parameters index
│   └── *.md             # Individual parameters
└── webhooks/
    ├── index.md         # Webhooks index
    └── *.md             # Individual webhooks

Command-Line Options ​

bash
python -m openapi_doc_generator --help

Input Sources ​

  • --openapi-url URL: Fetch OpenAPI spec from URL
  • --openapi-file FILE: Load OpenAPI spec from local file
  • --typescript-file FILE: TypeScript definitions file

Output Configuration ​

  • --output-dir DIR: Output directory (default: ./docs)
  • --output-format FORMAT: Output format (markdown, html, json)
  • --clean: Clean output directory before generation

SDK Integration ​

  • --sdk-name NAME: SDK name for integration
  • --sdk-lib-path PATH: Path to SDK source code
  • --sdk-client-pattern PATTERN: Pattern to identify client classes

Documentation Options ​

  • --no-indexes: Skip generating index files
  • --no-cross-refs: Skip cross-references
  • --no-examples: Skip examples
  • --no-typescript: Skip TypeScript definitions
  • --no-openapi-schemas: Skip OpenAPI schemas

General Options ​

  • --config FILE: Load configuration from file
  • --verbose: Enable verbose output
  • --debug: Enable debug mode

Extending the Tool ​

The modular architecture makes it easy to extend:

Adding New Output Formats ​

  1. Extend the OutputFormat enum in config.py
  2. Add format-specific generation methods to DocumentationGenerator
  3. Update the CLI to support the new format

Custom SDK Patterns ​

The SDK mapper can be configured to handle different patterns:

yaml
sdks:
  - name: "custom"
    lib_path: "./src/clients"
    client_pattern: "extends BaseClient"
    method_pattern: "async (\\w+)\\s*\\((.*?)\\): Promise<(.*)>"

Custom Templates ​

While not implemented in this version, the architecture supports adding template-based generation for consistent styling across different projects.

Troubleshooting ​

Common Issues ​

  1. "OpenAPI file not found": Ensure the file path is correct and accessible
  2. "No SDK methods found": Check the client pattern matches your SDK structure
  3. "Failed to parse TypeScript definitions": Ensure the TypeScript file is valid and follows expected patterns

Debug Mode ​

Enable debug mode for detailed information:

bash
python -m openapi_doc_generator --config config.yaml --debug

Verbose Output ​

Use verbose mode to see detailed progress:

bash
python -m openapi_doc_generator --config config.yaml --verbose

Migration from Node.js Script ​

This Python tool is designed to replace the existing Node.js script with several improvements:

Advantages ​

  • Better OpenAPI Handling: Uses proper JSON/YAML parsing instead of complex regex
  • Modular Architecture: Each component can be used independently
  • Enhanced Configuration: Support for multiple configuration formats and inheritance
  • Better Error Handling: Comprehensive validation and error reporting
  • Extensibility: Easy to add new features and output formats
  • Performance: Better handling of large specifications

Migration Steps ​

  1. Install the Python tool and dependencies
  2. Create a configuration file based on your current script usage
  3. Test with your existing OpenAPI specification
  4. Replace the Node.js script calls with Python script calls
  5. Update any CI/CD pipelines

Contributing ​

The tool is designed to be easily extensible. Key areas for contribution:

  • Additional output formats (HTML templates, PDF generation)
  • Enhanced SDK pattern matching
  • OpenAPI specification validation
  • Performance optimizations
  • Additional CLI features

License ​

This tool is part of the Commerce Engine TypeScript SDK project.

Last updated: