Spec Shaver

A TypeScript/Node.js package to intelligently reduce OpenAPI schemas to a specified number of operations and size limit.

Features

• ✨ Smart Prioritization: Intelligently selects the most important operations based on entity importance and operation type
• 🧙 Interactive Wizard: Manually select operations by groups/tags or individually with undo support
• 📦 Size Optimization: Automatically reduces schema size by removing examples and truncating descriptions
• 🔧 Flexible Configuration: Customize via CLI flags or config file (.spec-shaver.json)
• 🎯 Schema Validity: Automatically includes all referenced schemas and validates output
• 🚀 CLI Tool: Easy-to-use command-line interface with color-coded output
• 📊 Progress Indicators: Real-time feedback with spinners and progress messages
• 🔍 Verbose Mode: Detailed logging for debugging and understanding operations
• ✅ Validation: Ensures reduced schemas are valid OpenAPI specifications
• 📚 Programmatic API: Use as a library in your own code

Command Comparison

| Command | Selection | Best For | |---------|-----------|----------| | reduce | Automatic | Quick reduction with algorithmic prioritization | | wizard | Interactive | Manual control - select by groups or individual endpoints | | fetch | Automatic | Fetching and reducing remote schemas via URL |

Installation

npm install spec-shaver
# or
pnpm add spec-shaver
# or
yarn add spec-shaver

Quick Start

Configuration File (Recommended)

Create a .spec-shaver.json config file in your project:

npx spec-shaver init

This creates a default config file you can customize:

{
  "maxActions": 30,
  "maxSizeBytes": 1048576,
  "coreEntities": ["users", "accounts", "organizations"],
  "includeExamples": false,
  "maxDescriptionLength": 200,
  "output": "reduced_schema.json"
}

Then run commands without repeating options:

npx spec-shaver reduce --input schema.json

Running Locally (Development)

# Install dependencies
pnpm install

# Build and run
pnpm dev reduce --input schema.json --output reduced.json

# Or build first, then run
pnpm build
pnpm start reduce --input schema.json --output reduced.json

# Or run directly with node
node dist/cli.js reduce --input schema.json

As a CLI Tool (After Install)

npx spec-shaver reduce --input schema.json --output reduced.json

Fetch and reduce from a URL:

npx spec-shaver fetch --url https://api.example.com/openapi.json

Interactive wizard - select exactly which endpoints to keep:

npx spec-shaver wizard --input schema.json --output reduced.json

As a Library

import { OpenAPIReducer, SchemaFetcher } from 'spec-shaver';
import * as fs from 'fs';

// Load your OpenAPI schema
const schemaContent = fs.readFileSync('openapi.json', 'utf8');
const schema = JSON.parse(schemaContent);

// Create reducer with options
const reducer = new OpenAPIReducer({
  maxActions: 30,
  maxSizeBytes: 1024 * 1024, // 1MB
  coreEntities: ['users', 'orders', 'products'],
  includeExamples: false,
});

const result = reducer.reduce(schema);

console.log(`Reduced to ${result.reducedOperationCount} operations`);
console.log(`Size: ${(result.sizeBytes / 1024 / 1024).toFixed(2)} MB`);

// Or fetch from a URL
const remoteSchema = await SchemaFetcher.fetch({ url: 'https://api.example.com/openapi.json' });
const remoteResult = reducer.reduce(remoteSchema);

CLI Usage

Global Options

All commands support these global options:

-v, --verbose         Enable verbose logging (detailed operation info)
-q, --quiet          Suppress all output except errors
-c, --config <file>  Path to config file (default: .spec-shaver.json)

Initialize Config File

spec-shaver init [options]

Options:
  -o, --output <file>  Config file path (default: ".spec-shaver.json")

Example:

spec-shaver init
# Creates .spec-shaver.json with default settings

Reduce Local File

spec-shaver reduce [options]

Options:
  -i, --input <file>        Input schema file (required)
  -o, --output <file>       Output file path (default: "reduced_schema.json")
  -a, --actions <number>    Maximum number of actions (default: 30)
  -s, --size <bytes>        Maximum size in bytes (default: 1048576)
  -m, --methods <methods>   Filter by HTTP methods (comma-separated, e.g., "get,post")
  --include-examples        Include examples in schema (default: false)
  --resolve-refs            Resolve all $ref references by inlining them (default: false)
  -h, --help                Display help

Example:

# Basic usage
spec-shaver reduce --input original-schema.json --output reduced-schema.json

# With verbose logging
spec-shaver reduce -v --input schema.json --actions 20

# Using config file
spec-shaver reduce --input schema.json --config my-config.json

# Quiet mode (only errors)
spec-shaver reduce -q --input schema.json

Fetch from URL

spec-shaver fetch [options]

Options:
  -u, --url <url>           URL to fetch OpenAPI schema from (required)
  -H, --header <header...>  HTTP headers (format: "Key: Value")
  -o, --output <file>       Output file path (default: "reduced_schema.json")
  -a, --actions <number>    Maximum number of actions (default: 30)
  -s, --size <bytes>        Maximum size in bytes (default: 1048576)
  -m, --methods <methods>   Filter by HTTP methods (comma-separated, e.g., "get,post")
  --include-examples        Include examples in schema (default: false)
  --resolve-refs            Resolve all $ref references by inlining them (default: false)
  -h, --help                Display help

Example:

# Fetch from URL
spec-shaver fetch --url https://api.example.com/openapi.json

# With authentication
spec-shaver fetch \
  --url https://api.example.com/openapi.json \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --output my-schema.json

# With verbose logging
spec-shaver fetch -v --url https://api.example.com/openapi.json --actions 25

Interactive Wizard

The wizard lets you interactively select which operations to include:

spec-shaver wizard [options]

Options:
  -i, --input <file>        Input schema file
  -u, --url <url>           URL to fetch OpenAPI schema from
  -H, --header <header...>  HTTP headers for URL fetch
  -o, --output <file>       Output file path (default: "reduced_schema.json")
  --include-examples        Include examples in schema (default: false)
  --resolve-refs            Resolve all $ref references by inlining them (default: false)
  -h, --help                Display help

The wizard offers three selection modes:

1. Select by groups/tags - Choose entire groups of related endpoints
2. Select individual operations - Pick specific endpoints one by one
3. Keep all operations - Include everything (only optimize size)

New in v1.1: Navigate back through wizard steps with the "Go back" option!

Example:

# Interactive selection from file
spec-shaver wizard --input openapi.json --output reduced.json

# Interactive selection from URL
spec-shaver wizard --url https://api.example.com/openapi.json

# With verbose logging to see what's happening
spec-shaver wizard -v --input openapi.json

Programmatic API

reduceFromURL(url, options?)

Fetch and reduce any OpenAPI schema from a URL.

import { reduceFromURL } from 'spec-shaver';

const result = await reduceFromURL('https://api.example.com/openapi.json', {
  maxActions: 50,
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});

OpenAPIReducer Class

For more control, use the reducer class directly:

import { OpenAPIReducer } from 'spec-shaver';
import * as fs from 'fs';

// Load schema from file
const schemaContent = fs.readFileSync('openapi.json', 'utf8');
const schema = JSON.parse(schemaContent);

// Create reducer with options
const reducer = new OpenAPIReducer({
  maxActions: 30,
  maxSizeBytes: 1024 * 1024,
  coreEntities: ['users', 'orders', 'products'],
  includeExamples: false,
  maxDescriptionLength: 200,
});

// Reduce the schema
const result = reducer.reduce(schema);

// Save to file
fs.writeFileSync('reduced.json', JSON.stringify(result.schema, null, 2));

// Access result information
console.log('Operations:', result.operations);
console.log('Original count:', result.originalOperationCount);
console.log('Reduced count:', result.reducedOperationCount);
console.log('Size:', result.sizeBytes);

Configuration Options

Config File

Create a .spec-shaver.json file in your project root:

{
  "maxActions": 30,
  "maxSizeBytes": 1048576,
  "coreEntities": [
    "users",
    "accounts",
    "organizations",
    "projects",
    "items",
    "resources",
    "events",
    "messages",
    "files",
    "settings"
  ],
  "includeExamples": false,
  "maxDescriptionLength": 200,
  "resolveRefs": false,
  "output": "reduced_schema.json"
}

CLI options override config file settings.

ReducerOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxActions | number | 30 | Maximum number of operations to include | | maxSizeBytes | number | 1048576 (1MB) | Maximum schema size in bytes | | coreEntities | string[] | See below | Entities to prioritize | | includeExamples | boolean | false | Whether to include example fields | | maxDescriptionLength | number | 200 | Maximum length for descriptions | | resolveRefs | boolean | false | Resolve all $ref references by inlining them | | methodFilter | string[] | undefined | Filter operations by HTTP methods |

Default Core Entities

[
  'users',
  'accounts',
  'organizations',
  'projects',
  'items',
  'resources',
  'events',
  'messages',
  'files',
  'settings',
]

How It Works

1. Operation Prioritization

Operations are scored based on:

• Entity Importance (100 points): Paths containing core entities
• HTTP Method (20-50 points):
  • GET: 50 points
  • POST: 40 points
  • PATCH/PUT: 30 points
  • DELETE: 20 points
• Endpoint Type (10-15 points):
  • Collection endpoints (e.g., /users): 15 points
  • Single resource endpoints (e.g., /users/{id}): 10 points
• Documentation Quality (5 points): Operations with clear summaries

2. Schema Inclusion

The reducer automatically includes all referenced schemas from the components/schemas section by:

1. Scanning all selected operations for $ref references
2. Recursively resolving nested schema references
3. Including only the schemas that are actually used

3. Size Optimization

If the reduced schema exceeds the size limit, the reducer applies optimizations in order:

1. Remove example and examples fields from component schemas
2. Remove examples from path operations
3. Truncate descriptions longer than maxDescriptionLength

Output Format

ReducerResult

interface ReducerResult {
  schema: OpenAPISchema;              // The reduced OpenAPI schema
  originalOperationCount: number;     // Number of operations in original schema
  reducedOperationCount: number;      // Number of operations in reduced schema
  sizeBytes: number;                  // Size of reduced schema in bytes
  operations: Array<{                 // List of included operations
    method: string;
    path: string;
    summary?: string;
  }>;
}

Examples

Customize Core Entities

const reducer = new OpenAPIReducer({
  maxActions: 20,
  coreEntities: ['workspaces', 'members', 'projects'],
});

Include Examples and Increase Size Limit

const reducer = new OpenAPIReducer({
  maxActions: 50,
  maxSizeBytes: 2 * 1024 * 1024, // 2MB
  includeExamples: true,
});

Reduce from Local File

import { OpenAPIReducer } from 'spec-shaver';
import * as fs from 'fs';

const schemaContent = fs.readFileSync('schema.json', 'utf8');
const schema = JSON.parse(schemaContent);

const reducer = new OpenAPIReducer({ maxActions: 25 });
const result = reducer.reduce(schema);

fs.writeFileSync('output.json', JSON.stringify(result.schema, null, 2));

Development

Setup

git clone https://github.com/gfargo/spec-shaver.git
cd spec-shaver
pnpm install

Build

pnpm build

Run Locally

# Run CLI after building
pnpm start reduce --input schema.json

# Build and run in one command
pnpm dev reduce --input schema.json

Testing

pnpm test

Linting

pnpm lint

Documentation

• Getting Started - Quick start guide
• Contributing - Contribution guidelines
• Publishing - How to publish to NPM
• Structure - Package structure details
• Project Summary - High-level overview
• Roadmap - Planned features and improvements
• Changelog - Version history

What's New in v1.1

v1.1.2 - Reference Resolution (Latest)

New Feature:

• --resolve-refs flag to inline all $ref references for better compatibility with OpenAI GPT and other tools
• Available in all commands: fetch, reduce, and wizard
• Handles circular references gracefully
• Can be configured via resolveRefs option in config file

v1.1.1 - Bug Fixes & Performance

Fixed:

• Missing parameters and responses in reduced schemas - now properly includes all component definitions for full OpenAI GPT compatibility
• Resolved OpenAI GPT action validator errors about missing parameter definitions

Performance Improvements:

• ~30% faster processing through optimized string operations and caching
• Reduced memory usage with custom deep clone implementation
• Eliminated redundant size calculations during optimization

v1.1.0 - Enhanced CLI Experience

Color-Coded Output

Operations are now displayed with color-coded HTTP methods for better readability:

• GET (green), POST (blue), PUT/PATCH (yellow), DELETE (red)

Config File Support

Create a .spec-shaver.json file to avoid repeating CLI options:

spec-shaver init  # Creates default config
spec-shaver reduce --input schema.json  # Uses config automatically

Verbose & Quiet Modes

• -v, --verbose - See detailed operation logs
• -q, --quiet - Suppress all output except errors

Schema Validation

Automatically validates both input and output schemas to ensure they're valid OpenAPI specs.

Progress Indicators

Real-time feedback with spinners during long operations like fetching and reducing schemas.

Wizard Improvements

Navigate back through wizard steps with the "Go back" option - no more starting over!

License

MIT

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Issues

Found a bug or have a feature request? Please open an issue.