{"id":15957,"library":"api-smart-diff","title":"API Specification Diff Tool","description":"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.","status":"active","version":"1.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/udamir/api-smart-diff","tags":["javascript","jsonschema","diff","merge","compare","openapi","swagger","asyncapi","graphql","typescript"],"install":[{"cmd":"npm install api-smart-diff","lang":"bash","label":"npm"},{"cmd":"yarn add api-smart-diff","lang":"bash","label":"yarn"},{"cmd":"pnpm add api-smart-diff","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM named import for Node.js and modern build environments. For CJS, use 'require' syntax.","wrong":"const { apiCompare } = require('api-smart-diff')","symbol":"apiCompare","correct":"import { apiCompare } from 'api-smart-diff'"},{"note":"Import as a type for TypeScript projects to avoid runtime import issues.","wrong":"import { Diff } from 'api-smart-diff'","symbol":"Diff","correct":"import type { Diff } from 'api-smart-diff'"},{"note":"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.","wrong":"import { apiCompare } from 'api-smart-diff'; apiCompare(before, after)","symbol":"ApiSmartDiff","correct":"var { diffs, merged } = ApiSmartDiff.apiCompare(before, after)"}],"quickstart":{"code":"import { apiCompare } from 'api-smart-diff';\n\nconst beforeSpec = {\n  openapi: '3.0.0',\n  info: { title: 'My API', version: '1.0.0' },\n  paths: {\n    '/users': {\n      get: { summary: 'Get all users', operationId: 'getUsers' }\n    }\n  }\n};\n\nconst afterSpec = {\n  openapi: '3.0.0',\n  info: { title: 'My API', version: '1.0.1', description: 'Added new endpoint' },\n  paths: {\n    '/users': {\n      get: { summary: 'Retrieve users', operationId: 'getUsers' }\n    },\n    '/products': {\n      post: { summary: 'Create a product', operationId: 'createProduct' }\n    }\n  }\n};\n\nconst { diffs, merged } = apiCompare(beforeSpec, afterSpec);\n\nconsole.log('Detected Diffs:', JSON.stringify(diffs, null, 2));\nconsole.log('Merged Specification with Metadata:', JSON.stringify(merged, null, 2));","lang":"typescript","description":"Compares two OpenAPI 3.0 specifications, detailing the changes and providing a merged document."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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 });`","cause":"The API specification passed to `apiCompare` contains external `$ref` pointers that have not been pre-resolved or bundled.","error":"Error: Could not resolve reference: 'some-external-file.yaml'"},{"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.","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.","error":"TypeError: ApiSmartDiff.apiCompare is not a function"},{"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`.","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.","error":"Unexpected token '{' in JSON at position X"}],"ecosystem":"npm"}