Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
60 changes: 60 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -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": {
Expand Down
3 changes: 3 additions & 0 deletions resources/common/index.css
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,9 @@
display: flex;
flex-direction: column;
flex: 1;
word-break: break-all;
overflow-wrap: break-word;
white-space: normal;
}

.endpoint-path {
Expand Down
Loading