Registry / serialization / api-smart-diff

api-smart-diff

library1.0.6jsnpmunverified

api-smart-diff is a JavaScript/TypeScript library designed to compute detailed differences between two JSON-based API specifications. It currently supports OpenAPI 3.0, AsyncAPI 2.x, JSON Schema, and GraphQL via GraphApi. Version 1.0.6 is the current stable release, offering a robust set of features for API versioning and changelog generation. Key differentiators include its ability to classify changes into 'breaking', 'non-breaking', 'deprecated', and 'annotation' types, generate human-readable descriptions for each change, and resolve `$ref` pointers (with external bundling). It provides extensive customization options for comparison rules, classification, and output annotation, making it highly adaptable for various CI/CD pipelines and documentation generation tasks. The library works seamlessly in both Node.js and browser environments and ships with full TypeScript support.

serialization data

npm install api-smart-diff

github ↗package ↗

INSTALL

IMPORT

SIG · API-SMART-DIFF

api-smart-diff

serializationjavascriptv1.0.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

apiCompare

✓ import { apiCompare } from 'api-smart-diff'

✗ const { apiCompare } = require('api-smart-diff')

ESM named import for Node.js and modern build environments. For CJS, use 'require' syntax.

Diff

✓ import type { Diff } from 'api-smart-diff'

✗ import { Diff } from 'api-smart-diff'

Import as a type for TypeScript projects to avoid runtime import issues.

ApiSmartDiff

✓ var { diffs, merged } = ApiSmartDiff.apiCompare(before, after)

✗ import { apiCompare } from 'api-smart-diff'; apiCompare(before, after)

When used in browsers via CDN script, 'ApiSmartDiff' is exposed as a global variable. Do not use ES module imports without a bundler in this context.

Compares two OpenAPI 3.0 specifications, detailing the changes and providing a merged document.

import { apiCompare } from 'api-smart-diff'; const beforeSpec = { openapi: '3.0.0', info: { title: 'My API', version: '1.0.0' }, paths: { '/users': { get: { summary: 'Get all users', operationId: 'getUsers' } } } }; const afterSpec = { openapi: '3.0.0', info: { title: 'My API', version: '1.0.1', description: 'Added new endpoint' }, paths: { '/users': { get: { summary: 'Retrieve users', operationId: 'getUsers' } }, '/products': { post: { summary: 'Create a product', operationId: 'createProduct' } } } }; const { diffs, merged } = apiCompare(beforeSpec, afterSpec); console.log('Detected Diffs:', JSON.stringify(diffs, null, 2)); console.log('Merged Specification with Metadata:', JSON.stringify(merged, null, 2));

Debug

Known issues

gotchaFor API specifications containing external `$ref` pointers, these references must be bundled and resolved *before* passing the specification objects to `apiCompare`. The `api-smart-diff` library itself does not resolve external references.

fix

Use the `api-ref-bundler` package (`npm install api-ref-bundler`) to pre-process your API specifications and resolve all external `$ref`s before calling `apiCompare`.

affects: >=1.0.0

breakingSupport for Swagger 2.0 has been removed or was never fully implemented and is now explicitly unsupported. If your project relies on Swagger 2.0 diffing, this library will not work as expected.

fix

Migrate your Swagger 2.0 specifications to OpenAPI 3.0 or an officially supported format. Alternatively, consider using a different tool that specifically supports Swagger 2.0.

affects: >=1.0.0

gotchaAsyncAPI 3.x and gRPC specification comparisons are currently on the roadmap and are not yet supported. Attempting to diff these specification types will likely result in incorrect or incomplete output.

fix

Ensure your AsyncAPI specifications are version 2.x or earlier. For gRPC, no direct support is available; you may need to convert gRPC definitions to a supported format like JSON Schema or use a specialized gRPC diffing tool.

affects: >=1.0.0

gotchaWhen using `api-smart-diff` in a browser environment via the CDN script, the library exposes a global variable `ApiSmartDiff`. Attempting to use ES module `import` syntax without a proper module bundler will fail.

fix

Access the main function through the global `ApiSmartDiff.apiCompare(before, after)` object. If you need ES module syntax in the browser, integrate a module bundler like Webpack or Rollup into your build process.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Could not resolve reference: 'some-external-file.yaml'

The API specification passed to `apiCompare` contains external `$ref` pointers that have not been pre-resolved or bundled.

fix

Install and use `api-ref-bundler` to resolve all external references in your `before` and `after` specification objects before passing them to `apiCompare`. Example: `const bundledSpec = await bundle({ spec: originalSpec });`

TypeError: ApiSmartDiff.apiCompare is not a function

This error typically occurs in a browser environment when attempting to call `apiCompare` directly without referencing the global `ApiSmartDiff` object, or if the CDN script failed to load.

fix

Ensure the CDN script has loaded correctly in your HTML. Access the function via `ApiSmartDiff.apiCompare(before, after)`. If using a module bundler, verify your import statement for `apiCompare` is correct.

Unexpected token '{' in JSON at position X

One of the input API specifications (`before` or `after`) is not valid JSON or contains syntax errors, which prevents the library from parsing it correctly.

fix

Validate your API specification files (OpenAPI, AsyncAPI, JsonSchema) against their respective schemas or use a linter to identify and correct any JSON syntax errors before passing them to `apiCompare`.

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/udamir/api-smart-diff ↗

packagehttps://www.npmjs.com/package/api-smart-diff ↗