diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 185a165..f97f0a1 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -12,7 +12,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - node: [18, 20, 22] + node: [20, 22, 24] name: Node ${{ matrix.node }} test steps: - uses: actions/checkout@v4 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3950e65 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,60 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Commands + +### Development Commands +- `npm run lint` - Run ESLint for code linting +- `npm run lint:fix` - Run ESLint with automatic fixes +- `npm run test` - Run Jest tests with experimental VM modules support + +### Testing the CLI Tool +- `npx openapi-generate-html -i openapi.json` - Generate HTML from OpenAPI spec +- `npx openapi-generate-html -i openapi.json --theme=dark` - Generate with dark theme +- `npx openapi-generate-html -i openapi.json --ui=swagger --output=custom.html` - Generate with Swagger UI + +## Architecture + +This is a Node.js CLI tool that generates standalone HTML documentation from OpenAPI specifications. The tool creates self-contained HTML files with all assets embedded. + +### Core Components + +**Main Entry Point (`src/index.js`)** +- CLI argument parsing using Commander.js +- Interactive prompts using Inquirer.js +- Three-phase workflow: get options → render HTML → write file + +**Template System (`resources/*/`)** +- Three UI options: Stoplight Elements, Swagger UI, Redoc +- Each UI has: `template.ejs`, `index.css`, `index.js` +- Templates use EJS with embedded CSS/JS content and OpenAPI data + +**Validation (`src/utils/validate.js`)** +- Input validation for CLI commands and interactive prompts +- Supports JSON/YAML files and URLs +- Enforces HTML output format + +**Constants (`src/constants/index.js`)** +- UI types: `['stoplight', 'swagger', 'redoc']` +- Themes: `['light', 'dark']` +- File extensions: `['.json', '.yaml', '.yml']` + +### Key Processing Steps + +1. **Input Resolution**: Accepts file paths or URLs, validates format +2. **$ref Resolution**: Uses `@apidevtools/json-schema-ref-parser` to bundle external references +3. **Template Rendering**: EJS templates embed CSS, JS, and OpenAPI data into single HTML file +4. **Output Generation**: Creates standalone HTML with no external dependencies + +### File Structure Logic + +- `src/index.js` - Main orchestration and rendering logic +- `src/utils/validate.js` - All input validation functions +- `src/constants/index.js` - Configuration constants +- `resources/{ui}/` - UI-specific templates and assets +- Tests are co-located with source files (e.g., `validate.test.js`) + +### Testing + +Uses Jest with ES modules (`--experimental-vm-modules` flag required). Tests focus on validation functions and CLI argument handling. \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 49abf4b..62827c1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "openapi-generate-html", - "version": "0.5.2", + "version": "0.5.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "openapi-generate-html", - "version": "0.5.2", + "version": "0.5.3", "license": "MIT", "dependencies": { "@apidevtools/json-schema-ref-parser": "^13.0.5", diff --git a/package.json b/package.json index 99da9df..d58a7b6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "openapi-generate-html", - "version": "0.5.2", + "version": "0.5.3", "description": "Generate standalone HTML from OpenAPI Specification", "type": "module", "bin": { diff --git a/resources/common/index.css b/resources/common/index.css index 2315f73..0adbe17 100644 --- a/resources/common/index.css +++ b/resources/common/index.css @@ -61,6 +61,9 @@ display: flex; flex-direction: column; flex: 1; + word-break: break-all; + overflow-wrap: break-word; + white-space: normal; } .endpoint-path {