@apivexa/openapi

OpenAPI parser, $ref resolver, and security-hardened loader for ApiVexa.

Part of ApiVexa — AI-powered API User Guide Generator.

Install

npm install @apivexa/openapi

Features

• Parses OpenAPI 2.0, 3.0, 3.1 and Swagger 2.0 (YAML and JSON)
• Resolves $ref chains including circular-reference detection
• Loads from local file, remote URL, or raw string
• SSRF protection — remote fetches require an explicit host allowlist
• Path traversal guard — rejects ../ segments before any filesystem access
• Content-Length pre-check — oversized responses are rejected before buffering
• Structural validation against the OpenAPI schema

Usage

import { ingest } from '@apivexa/openapi';

// From a local file
const api = await ingest({ type: 'file', path: './openapi.yaml' });

// From a URL (host must be in allowedHosts)
const api = await ingest(
  { type: 'url', url: 'https://api.example.com/openapi.json' },
  { allowedHosts: ['api.example.com'] },
);

// From raw content
const api = await ingest({ type: 'raw', content: yamlString, format: 'yaml' });

console.log(api.info.title);          // "My API"
console.log(api.operations.length);  // 42

Security

All OpenAPI documents are treated as untrusted input. See SECURITY.md for details.

Full documentation