tessl/npm-oas-normalize

Tooling for converting, validating, and parsing OpenAPI, Swagger, and Postman API definitions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

OAS Normalize

Name: tessl/npm-oas-normalize
Author: tessl

OAS Normalize is a comprehensive TypeScript library that provides tooling for converting, validating, and parsing OpenAPI, Swagger, and Postman API definitions. It offers a unified interface for handling diverse API specification formats with robust error handling, automatic format conversion, and built-in validation capabilities.

Package Information

Package Name: oas-normalize
Package Type: npm
Language: TypeScript
Installation: npm install oas-normalize

Core Imports

import OASNormalize from "oas-normalize";

For CommonJS:

const OASNormalize = require("oas-normalize");

Basic Usage

import OASNormalize from "oas-normalize";

// Initialize with API definition (URL, file path, JSON object, etc.)
const oas = new OASNormalize(
  'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml'
);

// Validate the API definition
try {
  await oas.validate();
  console.log('API definition is valid!');
} catch (error) {
  console.error('Validation failed:', error.message);
}

// Convert to OpenAPI format
const openapi = await oas.convert();

// Bundle external references
const bundled = await oas.bundle();

// Dereference all $ref pointers
const dereferenced = await oas.dereference();

Architecture

OAS Normalize is built around several key components:

Multi-format Support: Handles OpenAPI 3.x, Swagger 2.0, and Postman collections seamlessly
Input Flexibility: Accepts various input types including URLs, file paths, JSON objects, YAML strings, and Buffers
Automatic Conversion: Converts Swagger 2.0 and Postman collections to OpenAPI 3.x format
Reference Resolution: Bundles external $ref pointers and provides full dereferencing capabilities
Validation Engine: Comprehensive validation with detailed error reporting and customizable rulesets
Caching System: Built-in caching for improved performance on repeated operations

Capabilities

Core Processing

Main class for loading, processing, and manipulating API definitions with comprehensive format support and validation.

class OASNormalize {
  constructor(file: any, opts?: Options);
  
  // Load the original API definition
  async load(): Promise<Record<string, unknown>>;
  
  // Get specification type and version information
  async version(): Promise<{
    specification: 'openapi' | 'postman' | 'swagger';
    version: string | 'unknown';
  }>;
}

interface Options {
  colorizeErrors?: boolean;
  enablePaths?: boolean;
  parser?: ParserOptions;
}

Core Processing

Format Conversion

Automatic conversion capabilities for transforming Swagger and Postman collections to OpenAPI format.

class OASNormalize {
  // Convert API definition to OpenAPI format
  async convert(): Promise<OpenAPI.Document>;
}

Format Conversion

Reference Resolution

Advanced reference resolution for bundling external $ref pointers and dereferencing all references inline.

class OASNormalize {
  // Bundle external $ref pointers
  async bundle(): Promise<OpenAPI.Document>;
  
  // Dereference all $ref pointers inline
  async dereference(): Promise<OpenAPI.Document>;
  
  // Deprecated alias for dereference
  async deref(): Promise<OpenAPI.Document>;
}

Reference Resolution

Validation

Comprehensive validation system with detailed error reporting, contextual messages, and customizable validation rules.

class OASNormalize {
  // Validate API definition with detailed error reporting
  async validate(opts?: {
    parser?: ParserOptions;
  }): Promise<ValidationResult>;
}

interface ValidationResult {
  valid: boolean;
  warnings: WarningDetails[];
  errors: ErrorDetails[];
}

Validation

Error Handling

Custom error classes and utility functions for managing validation errors and compilation.

class ValidationError extends Error {
  constructor(message: string);
  name: 'ValidationError';
}

// Utility functions
function compileErrors(result: ValidationResult): string;

Error Handling

Utility Functions

Helper functions for type detection, schema validation, and input processing.

// Type detection and validation
function getType(obj: any): 'buffer' | 'json' | 'path' | 'string-json' | 'string-yaml' | 'url' | false;
function isOpenAPI(schema: Record<string, unknown>): boolean;
function isSwagger(schema: Record<string, unknown>): boolean;
function isPostman(schema: Record<string, unknown>): boolean;
function isAPIDefinition(schema: Record<string, unknown>): boolean;
function getAPIDefinitionType(schema: Record<string, unknown>): 'openapi' | 'postman' | 'swagger' | 'unknown';

// Data processing utilities
function stringToJSON(string: Record<string, unknown> | string): Record<string, unknown>;
function prepareURL(url: string): { options: RequestInit; url: string };
function isBuffer(obj: any): boolean;

Utility Functions

Install with Tessl CLI