swagger-diff

This package provides utils and CLI to compute the diff between two swagger API specifications. Output diff can be configured according to version change.

Purpose

• Identify breaking and smooth changes.
• Ensure API versioning consistency.
• Compute API changelogs.
• Prevent unexpected API changes.

Swagger Compatilibity

Supports only swagger spec 2.0.

Installation

Install using npm:

npm install swagger-diff

Usage

CLI

The binary allows you to use swagger-diff in CLI.

$ swagger-diff <old> <new>

It prints the diff between old and new swagger files according to configuration and returns false if any diff "error". It can also write the diff result in a JSON file. Use -h for option defails.

Note: old and new parameters can either be the file path or the URL of the swagger file.

Example of CLI output

Node

var SwaggerDiff = require('swagger-diff');

SwaggerDiff(oldSpec, newSpec, config).then(function (diff) {
  // Handle result
});

Note: on nodeJS, oldSpec and newSpec can either be a file path, a URL or a plain object. config can be a file path or a plain object.

Note: Please refer to How it works section for details about output.

Browsers

Dist folder contains an UMD bundle allowing you to either reference swagger-diff.min.js in your HTML or import module using Require.js.

Reference swagger-diff.min.js in your HTML and use the global variable SwaggerDiff.

<script src="node_modules/swagger-diff/dist/swagger-diff.min.js"></script>
<script>
  SwaggerDiff(oldSpec, newSpec, config).then(function (diff) {
    // Handle result
  });
</script>

Hosted versions of swagger-diff releases are available on JSDeliver CDN.

Note: in browser, oldSpec and newSpec can only be a URL or a plain object. config can only be a plain object.

Note: Please refer to How it works section for details about output.

Diffs

Swagger-Diff defines rules that performs ONE type of diff checking. These rules are separated in 2 groups:

• breaking change
• smooth change

Breaking changes

Examples:

• Delete path
• Rename path operationId
• Delete/Rename parametters
• Add a constraint on a parametter (like isRequired)
• Modify a response item

Smooth changes

Examples:

• Add a path
• Add a param
• Add response item
• Add/Update descriptions

Configuration

In the configuration file (default: .swagger-diff), you can customize the level of log you want for type of changes.

{
  "changes": {
    "breaks": 3,
    "smooths": 2
  }
}

It's also possible to define different level of logs according to version change.

{
  "changes": {
    "breaks": {
      "major": 2,
      "minor": 3,
      "patch": 3,
      "unchanged": 3
    },
    "smooths": {
      "major": 0,
      "minor": 1,
      "patch": 2,
      "unchanged": 3
    }
  }
}

Levels of log

3-error
2-warning
1-info
0-ignore

Configure specific rules

You can also configure specific level of logs for some rules.

{
  "rules": {
    "delete-path": 0,
    "add-path": {
      "major": 2,
      "minor": 3,
      "patch": 3,
      "unchanged": 3
    }
  }
}

How it works

To compute the diff, it exectutes a workflow composed of 4 main steps.

Preparation

Dereference

Resolve JSON references and dereference URIs.

Inline global definitions

Swagger spec 2.0 allows to specify global definitions for parameters, security, schemes, consumes and produces that can then be overriden when needed. It inlines these definitions in every paths objects.

Index definitions

parameters are indexed by their name in order to allow raw-diff to compare parameters nicely.

Raw diff

deep-diff lib is used to compute deep raw diff.

Rules application

Exectute each rule on each raw diff to output breakings and smooth changes.

Final diff

Post process diffs to output errors, warnings, infos according to configuration and version change.

Note: unmatchDiffs are the raw diffs that didn't much any rules. They can include breaking changes not implemented yet.