varsity/README.md

Varsity

A comprehensive OpenAPI parsing and validation library built with TypeScript and Bun. Varsity provides both a command-line interface and a programmatic API for validating OpenAPI specifications across all versions (2.0, 3.0.x, 3.1.0).

Features

• 🔍 Multi-version Support: Validates OpenAPI 2.0 (Swagger) and OpenAPI 3.0.x/3.1.0 specifications
• 📊 Comprehensive Reporting: Generate reports in JSON, YAML, HTML, and Markdown formats
• 🚀 High Performance: Built with Bun for fast execution
• 🛠️ Flexible Usage: Use as a CLI tool or import as a library
• ✅ AJV Integration: Robust validation using the industry-standard AJV library
• 📝 Detailed Error Reporting: Clear error messages with path information
• 🔧 Extensible: Support for custom validation rules and schemas
• 🎯 Type Safety: Full TypeScript support with comprehensive OpenAPI type definitions from oas-types
• 📋 Comprehensive Schemas: Uses official JSON schemas for accurate validation

Installation

bun install

Usage

Command Line Interface

Validate a specification

bun run src/cli.ts validate path/to/spec.json

Parse without validation

bun run src/cli.ts parse path/to/spec.json

Generate a report

bun run src/cli.ts report path/to/spec.json --format html --output report.html

Batch validation

bun run src/cli.ts batch spec1.json spec2.json spec3.json

Show supported versions

bun run src/cli.ts info

CLI Options

Validate Command

• -s, --strict: Enable strict validation mode
• -e, --examples: Validate examples in the specification
• -r, --references: Validate all references
• -v, --verbose: Show detailed output

Report Command

• -f, --format <format>: Report format (json, yaml, html, markdown)
• -o, --output <file>: Output file path
• -w, --warnings: Include warnings in report
• -m, --metadata: Include metadata in report

Programmatic Usage

Functional Approach (Recommended)

import { validate, parse, generateValidationReport } from './src/varsity.js';

// Parse and validate
const result = await validate('path/to/spec.json');

// Generate a report
const report = await generateValidationReport('path/to/spec.json', {
  format: 'json',
  includeWarnings: true,
  includeMetadata: true
});

// Parse without validation
const parsed = await parse('path/to/spec.json');

Factory Pattern (For Configuration)

import { createVarsity } from './src/varsity.js';

const varsity = createVarsity({
  defaultVersion: '3.0.3',
  strictMode: false,
  customSchemas: {},
  reportFormats: ['json']
});

// Use the configured instance
const result = await varsity.validate('path/to/spec.json');
const report = await varsity.generateReport('path/to/spec.json', {
  format: 'json',
  includeWarnings: true,
  includeMetadata: true
});

API Reference

Core Functions

Direct Functions

• validate(source: string, options?: ValidationOptions, config?: VarsityConfig): Promise<ValidationResult>
• parse(source: string): Promise<ParsedSpec>
• generateValidationReport(source: string, reportOptions: ReportOptions, validationOptions?: ValidationOptions, config?: VarsityConfig): Promise<string>
• saveValidationReport(source: string, reportOptions: ReportOptions, validationOptions?: ValidationOptions, config?: VarsityConfig): Promise<void>
• validateMultiple(sources: string[], options?: ValidationOptions, config?: VarsityConfig): Promise<ValidationResult[]>
• getSupportedVersions(): string[]

Factory Function

• createVarsity(config?: VarsityConfig): Creates a configured instance with methods

Individual Module Functions

• parseOpenAPISpec(source: string): Promise<ParsedSpec>
• validateBasicStructure(spec: any, version: OpenAPIVersion): boolean
• validateOpenAPISpec(spec: any, version: OpenAPIVersion, options?: ValidationOptions): ValidationResult
• generateReport(result: ValidationResult, options: ReportOptions): string
• saveReport(content: string, outputPath: string): void

Types

• ValidationResult: Contains validation results with errors and warnings
• ParsedSpec: Parsed specification with metadata
• ValidationOptions: Configuration for validation behavior
• ReportOptions: Configuration for report generation
• VarsityConfig: Global configuration for the library
• OpenAPISpec: Union type for all OpenAPI specification versions
• OpenAPIVersion: Supported OpenAPI version strings

Type Safety

Varsity leverages the comprehensive oas-types package for full TypeScript support:

import type { OpenAPI2, OpenAPI3, OpenAPI3_1 } from 'oas-types';

// All parsed specifications are properly typed
const result = await validate('spec.json');
// result.spec is typed as OpenAPISpec (OpenAPI2 | OpenAPI3 | OpenAPI3_1)

// Type guards for version-specific handling
if (result.version === '2.0') {
  const swaggerSpec = result.spec as OpenAPI2;
  // swaggerSpec.swagger, swaggerSpec.info, etc. are fully typed
}

Development

Running Tests

bun test

Building

bun run build

Linting

bun run lint

License

MIT