Spec Shaver

Intelligent OpenAPI Schema Reduction

A TypeScript CLI tool and library for intelligently reducing large OpenAPI specifications to meet size and operation constraints.

Overview

Spec Shaver solves a common problem developers face when working with OpenAPI specifications: many platforms and tools impose strict limits on API schema size and complexity. OpenAI’s Custom GPT actions, for example, require schemas under 1MB with no more than 30 operations. When your production API has 150+ endpoints and a 3.5MB spec file, manual reduction becomes tedious and error-prone.

This tool automatically prioritizes and selects the most important API operations while maintaining schema validity, resolving all dependencies, and optimizing file size.

Key Features

Smart Prioritization Algorithm

Automatically ranks API operations based on multiple factors:

• Core entity importance (users, accounts, projects, etc.)
• HTTP method significance (GET > POST > PATCH > DELETE)
• Endpoint type (collection vs single resource)
• Documentation quality and completeness

Interactive Wizard Mode

Manual control when automatic selection isn’t enough:

• Select operations by groups/tags or individually
• Navigate back through steps to refine selections
• Preview size estimates before generating output
• Three selection modes: groups, individual, or keep all

Schema Validation

Ensures output quality and compatibility:

• Validates input schemas before processing
• Validates reduced schemas after generation
• Automatic $ref dependency resolution
• Maintains OpenAPI 3.x compliance

Flexible Configuration

Adapt to any workflow:

• Project-level config files (.spec-shaver.json)
• CLI options for one-off customization
• Programmatic API for integration
• Verbose and quiet modes for different environments

Size Optimization

Multiple strategies to meet size constraints:

• Remove example values
• Truncate long descriptions
• Eliminate unused schema definitions
• Configurable optimization levels

Use Cases

OpenAI Custom GPT Actions

The primary use case – reduce large API specs to meet OpenAI’s 1MB/30 operation limits for Custom GPT actions. Transform your comprehensive API documentation into a focused, GPT-compatible schema in seconds.

Lightweight SDK Generation

Create focused API clients for specific use cases. Generate SDKs that only include the operations your application actually needs, reducing bundle size and improving developer experience.

API Documentation

Build targeted documentation for different audiences. Extract public-facing endpoints from internal APIs, or create role-specific documentation showing only relevant operations.

Testing and Development

Generate manageable test schemas from production APIs. Reduce complexity during development and testing without maintaining separate schema files.

CI/CD Integration

Automate schema reduction in build pipelines. Ensure consistent, optimized schemas across deployments with configuration files and quiet mode operation.

Technical Highlights

Built With TypeScript

• Full type safety and IntelliSense support
• Comprehensive type definitions for all APIs
• Strict mode enabled for reliability
• Modern ES2020+ features

Dual Interface

• CLI Tool: Fast, user-friendly command-line interface with color-coded output and progress indicators
• Library: Programmatic API for integration into existing tools and workflows

Production Ready

• Validates all input and output
• Handles edge cases and malformed schemas
• Clear error messages with actionable guidance
• Extensive documentation and examples

Developer Experience

• Interactive wizard with undo functionality
• Verbose mode for debugging
• Config file support for team consistency
• Zero-config defaults that just work

Installation

# Global installation
npm install -g spec-shaver

# Project dependency
npm install spec-shaver

# One-time use
npx spec-shaver reduce --input schema.json

# Global installation
npm install -g spec-shaver

# Project dependency
npm install spec-shaver

# One-time use
npx spec-shaver reduce --input schema.json

Quick Start

Automatic Reduction

# Reduce a local file
spec-shaver reduce --input openapi.json --output reduced.json

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

# Reduce a local file
spec-shaver reduce --input openapi.json --output reduced.json

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

Interactive Selection

# Launch the wizard
spec-shaver wizard --input openapi.json

# Launch the wizard
spec-shaver wizard --input openapi.json

Configuration

# Create config file
spec-shaver init

# Use config
spec-shaver reduce --input openapi.json

# Create config file
spec-shaver init

# Use config
spec-shaver reduce --input openapi.json

Performance

• Speed: Processes 3.5MB schemas in under 1 second
• Reduction: Typical 75% size reduction (3.5MB → 850KB)
• Operations: Reduces 150+ operations to 30 most relevant
• Validation: ~50-100ms overhead for schema validation

Architecture

Core Components

• Reducer: Prioritization algorithm and schema building
• Fetcher: HTTP client for remote schema retrieval
• Wizard: Interactive operation selection interface
• Validator: OpenAPI schema validation
• Logger: Color-coded output and progress indicators
• Config: Configuration file management

Prioritization Algorithm

1. Score each operation based on configurable criteria
2. Sort operations by priority score
3. Select top N operations
4. Recursively resolve all $ref dependencies
5. Optimize size if needed (remove examples, truncate descriptions)
6. Validate final schema

Technology Stack

• Language: TypeScript 5.3+
• Runtime: Node.js 16+
• CLI Framework: Commander.js
• Interactive Prompts: Inquirer.js
• Validation: openapi-schema-validator
• Output: Chalk (colors), Ora (spinners)

Project Stats

• Version: 1.1.0
• License: MIT
• Package Size: 17.1 KB (tarball)
• Dependencies: 6 production, 7 development
• TypeScript: Strict mode, full type coverage
• Documentation: Comprehensive guides and examples

Roadmap

v1.2.0 (Planned)

• Schema merging for multiple API specs
• Operation search and filtering in wizard
• Enhanced pagination for large schemas
• Save/load selection profiles

v1.3.0 (Future)

• Custom scoring functions
• Dry-run mode for previewing changes
• YAML format support
• Diff output showing excluded operations

v2.0.0 (Long-term)

• AI-powered entity detection
• API versioning support
• Documentation generation
• CI/CD integrations and GitHub Actions

Links

• GitHub: github.com/gfargo/spec-shaver
• NPM: npmjs.com/package/spec-shaver
• Documentation: Full documentation
• Changelog: Version history