API Reference

Programmatic API for OpenAPI Drift Guard.

Parser

parseAndNormalizeSpec()

Parse OpenAPI/Swagger spec file into normalized endpoints.

import { parseAndNormalizeSpec } from 'openapi-drift-guard'

const endpoints = parseAndNormalizeSpec('./openapi.yaml')
console.log(`Found ${endpoints.length} endpoints`)

Supported formats: OpenAPI 3.x (JSON/YAML), Swagger 2.0 (auto-converted)

Analyzer

createAnalyzer()

Create framework-specific code analyzer.

import { createAnalyzer } from 'openapi-drift-guard'

const analyzer = createAnalyzer('express', './src')
const endpoints = analyzer.analyze()

Available frameworks: express (v0.1.0), fastify/koa/nestjs/hono (v0.2.0)

Detector

detectDrifts()

Detect drifts between spec and code endpoints.

import { detectDrifts } from 'openapi-drift-guard'

const drifts = detectDrifts(specEndpoints, codeEndpoints)
for (const drift of drifts) {
  console.log(`${drift.severity}: ${drift.message}`)
}

8 drift types with 4 severity levels (critical/high/medium/low)

Types

NormalizedEndpoint

Unified endpoint model for both spec and code.

interface NormalizedEndpoint {
  method: HttpMethod
  path: string
  pathParams: Param[]
  queryParams: Param[]
  requestBody?: Schema
  responses: Response[]
  source: 'spec' | 'code'
}

DriftResult

Drift detection result with severity classification.

interface DriftResult {
  type: DriftType
  severity: Severity
  method: HttpMethod
  path: string
  message: string
  suggestions?: string[]
}

All Types

Complete type reference including HttpMethod, Severity, DriftType, Param, Schema, Response.

Error Classes

ValidationError

Thrown for invalid configuration or input.

ParseError

Thrown for spec parsing failures.

Utility Functions

Format Utilities

import {
  formatDriftItem,
  formatDriftReport,
  formatEndpointShort,
  formatSeverityBadge,
  truncate,
} from 'openapi-drift-guard'

Config Utilities

import { getDefaultConfig, mergeConfig, validateConfig } from 'openapi-drift-guard'

const config = mergeConfig({ framework: 'express', codeDir: './src' })
validateConfig(config)