API Specification Diff Tool

1.0.6 · active · verified Tue Apr 21

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.

Common errors

```
Error: Could not resolve reference: 'some-external-file.yaml'
```
cause 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
```
cause 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
```
cause 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`.

Warnings

gotcha For 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`.
breaking Support 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.
gotcha AsyncAPI 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.
gotcha When 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.

Install

npm install api-smart-diff npm
yarn add api-smart-diff yarn
pnpm add api-smart-diff pnpm

Imports

apiCompare
wrong:
```
const { apiCompare } = require('api-smart-diff')
```
correct:
```
import { apiCompare } from 'api-smart-diff'
```
ESM named import for Node.js and modern build environments. For CJS, use 'require' syntax.
Diff
wrong:
```
import { Diff } from 'api-smart-diff'
```
correct:
```
import type { Diff } from 'api-smart-diff'
```
Import as a type for TypeScript projects to avoid runtime import issues.
ApiSmartDiff
wrong:
```
import { apiCompare } from 'api-smart-diff'; apiCompare(before, after)
```
correct:
```
var { diffs, merged } = ApiSmartDiff.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.

Quickstart

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));

view raw JSON →