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

Core Processing

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

Core functionality for loading, initializing, and processing API definitions with comprehensive format support and flexible input handling.

Capabilities

OASNormalize Class

Main class that provides a unified interface for working with OpenAPI, Swagger, and Postman API definitions.

/**
 * Main class for normalizing API definitions across multiple formats
 */
class OASNormalize {
  constructor(file: any, opts?: Options);
  
  // Instance properties
  cache: {
    bundle?: OpenAPI.Document | false;
    convert?: OpenAPI.Document | false;
    deref?: OpenAPI.Document | false;
    load?: Record<string, unknown> | false;
  };
  file: any;
  opts: Options;
  type: ReturnType<typeof getType>;
}

interface Options {
  /** Enable colorized validation errors (default: false) */
  colorizeErrors?: boolean;
  /** Allow local file path access for security (default: false) */
  enablePaths?: boolean;
  /** OpenAPI parser configuration options */
  parser?: ParserOptions;
}

Usage Examples:

import OASNormalize from "oas-normalize";

// Initialize with different input types
const oasFromURL = new OASNormalize('https://api.example.com/openapi.json');
const oasFromFile = new OASNormalize('./api-spec.yaml', { enablePaths: true });
const oasFromObject = new OASNormalize({ openapi: '3.0.0', info: { title: 'API' } });
const oasFromString = new OASNormalize('{"openapi": "3.0.0", "info": {"title": "API"}}');

// With options
const oas = new OASNormalize(apiSpec, {
  colorizeErrors: true,
  enablePaths: true,
  parser: {
    validate: {
      rules: {
        openapi: {
          'path-parameters-not-in-path': 'warning'
        }
      }
    }
  }
});

Load Method

Load and retrieve the API definition that OAS Normalize was initialized with, resolving URLs and file paths as needed.

/**
 * Load and return the API definition
 * Resolves URLs, file paths, and various input formats to a JSON object
 * @returns Promise resolving to the loaded API definition
 */
async load(): Promise<Record<string, unknown>>;

Usage Examples:

// Load from various sources
const oas = new OASNormalize('https://petstore.swagger.io/v2/swagger.json');
const definition = await oas.load();
console.log(definition.info.title); // "Swagger Petstore"

// Load from local file (requires enablePaths)
const oasLocal = new OASNormalize('./petstore.yaml', { enablePaths: true });
const localDef = await oasLocal.load();

// Load from JSON object (returns as-is)
const oasObj = new OASNormalize({ openapi: '3.0.0', info: { title: 'My API' } });
const objDef = await oasObj.load();

// Load from YAML string
const yamlString = `
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
`;
const oasYaml = new OASNormalize(yamlString);
const yamlDef = await oasYaml.load();

Version Method

Retrieve specification type and version information about the supplied API definition.

/**
 * Get version information about the API definition
 * @returns Promise resolving to specification type and version details
 */
async version(): Promise<{
  specification: 'openapi' | 'postman' | 'swagger';
  version: string | 'unknown';
}>;

Usage Examples:

// Check OpenAPI version
const oas = new OASNormalize(openapi31Spec);
const { specification, version } = await oas.version();
console.log(specification); // "openapi"
console.log(version); // "3.1.0"

// Check Swagger version
const swagger = new OASNormalize(swagger20Spec);
const swaggerInfo = await swagger.version();
console.log(swaggerInfo.specification); // "swagger"
console.log(swaggerInfo.version); // "2.0"

// Check Postman collection
const postman = new OASNormalize(postmanCollection);
const postmanInfo = await postman.version();
console.log(postmanInfo.specification); // "postman"
console.log(postmanInfo.version); // "2.1.0" or "unknown"

Supported Input Types

URLs (HTTP/HTTPS)

const oas = new OASNormalize('https://api.example.com/openapi.json');
const oasWithAuth = new OASNormalize('https://user:pass@api.example.com/spec.yaml');

Automatically handles GitHub blob URLs (converts to raw URLs)
Supports basic authentication in URL
Handles both JSON and YAML content types

File Paths

const oas = new OASNormalize('./api-spec.yaml', { enablePaths: true });
const oasAbsolute = new OASNormalize('/absolute/path/to/spec.json', { enablePaths: true });

Requires enablePaths: true option for security
Supports both relative and absolute paths
Handles JSON and YAML files

JSON Objects

const spec = { openapi: '3.0.0', info: { title: 'My API' } };
const oas = new OASNormalize(spec);

Direct JavaScript objects
No additional processing required

String Content

// JSON strings
const jsonString = '{"openapi": "3.0.0", "info": {"title": "API"}}';
const oasJson = new OASNormalize(jsonString);

// YAML strings
const yamlString = 'openapi: 3.0.0\ninfo:\n  title: API';
const oasYaml = new OASNormalize(yamlString);

Automatically detects JSON vs YAML format
Parses content appropriately

Buffer Objects

import fs from 'fs';
const buffer = fs.readFileSync('./api-spec.yaml');
const oas = new OASNormalize(buffer);

Converts buffer to string and processes as YAML/JSON
Useful for programmatic file handling

Security Considerations

Local File Access

Local file path access is disabled by default for security reasons:

// This will throw an error
const oas = new OASNormalize('./local-file.yaml');
await oas.load(); // Error: Use `opts.enablePaths` to enable accessing local files.

// Enable with explicit option
const oasSafe = new OASNormalize('./local-file.yaml', { enablePaths: true });
await oasSafe.load(); // Works

Reference Resolution Security

When enablePaths is disabled, external file references in $ref pointers are blocked:

const specWithRef = {
  openapi: '3.0.0',
  paths: {
    '/': {
      get: {
        parameters: [{
          schema: { $ref: '/etc/passwd' }  // This will be blocked
        }]
      }
    }
  }
};

const oas = new OASNormalize(specWithRef, { enablePaths: false });
await oas.validate(); // Will throw error about unable to resolve $ref

Install with Tessl CLI