api-smart-diff

api-smart-diff

This package provides utils to compute the diff between two API specifications.

Purpose

• Generate API changelog
• Identify breaking changes
• Ensure API versioning consistency

Supported API specifications

• OpenApi 3.0
• AsyncApi 2.1
• JsonSchema
• Swagger 2.0 (Roadmap)
• graphql (Roadmap)
• gRPC (Roadmap)

Features

• Generate diff for supported specifications
• Generate merged spec with changes in metadata
• Classify all changes as breaking, non-breaking, annotation
• Supports custom classification rules
• Supports custom match rules for array items and object keys
• Resolves all $ref pointers, including external
• Typescript syntax support out of the box
• No dependencies, can be used in nodejs or browser

Installation

npm install api-smart-diff --save

Usage

Nodejs

import { apiDiff } from 'api-smart-diff'

const diff = apiDiff(oldSpec, newSpec, { rules: "OpenApi3" })
// {
//   action: "add" | "remove" | "replace",
//   after: 'value in newSpec',
//   before: 'value in oldSpec',
//   path: ['path, 'in', 'array', 'format'],
//   type: "annotation" | "breaking" | "non-breaking" | "unclassified"
// }

const merge = apiMerge(oldSpec, newSpec, { rules: "OpenApi3" })

Browsers

A browser version of api-smart-diff is also available via CDN:

<script src="https://cdn.jsdelivr.net/npm/api-smart-diff@latest/browser/api-smart-diff.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/api-smart-diff@latest/browser/api-smart-diff.js"></script>

Reference api-smart-diff.min.js in your HTML and use the global variable ApiSmartDiff.

<script>
  var diff = ApiSmartDiff.apiDiff(oldSpec, newSpec, { rules: "OpenApi3" })
  var merge = ApiSmartDiff.apiMerge(oldSpec, newSpec, { rules: "OpenApi3" })
</script>

License

MIT