openapi-diff

OpenAPI Diff

A CLI tool to identify differences between Swagger/OpenAPI specs.

Requirements

• nodejs 8.x or higher (tested using 8.x, 10.x and 12.x)
• npm 3.x or higher (tested using 3.x and 6.x)

Installation

Install the tool using npm and add it to the package.json

npm install openapi-diff --save-dev

Avoid installing the tool globally as this will lead to problems when multiple codebases try to use different versions of the tool on the same machine.

Usage

Invoke the tool with two paths to Swagger/OpenAPI files in order to find differences between them, these paths can either be paths to the specs in the local filesystem or URLs to the specs, both JSON and YAML are supported.

./node_modules/.bin/openapi-diff /path/to/source/openapi.json /path/to/destination/openapi.json
./node_modules/.bin/openapi-diff /path/to/source/openapi.yml /path/to/destination/openapi.yml

The tool's output will display the amount and type of changes, and then list the changes with the relevant info. Changes are classified as follows:

• Breaking: changes that would make existing consumers incompatible with the API (deletion of paths, adding required properties...)
• Non-breaking: changes that would not make existing consumers incompatible with the API (addition of paths, turning a required property into optional...)
• Unclassified: changes that have been detected by the tool but can't be classified (modifications to X-Properties and other unforeseen changes)

The command will exit with an exit code 1 if any breaking changes were found, so that you can fail builds in CI when this happens.

Feature support

See SPEC_SUPPORT.md for details on which Swagger/OpenApi keywords the tool currently supports detecting differences within.

Changelog

See CHANGELOG.md

Contributing

See CONTRIBUTING.md

License

See LICENSE.txt

Changelog

0.23.1 (2020-01-28)

<a name="0.23.0"></a>

Features

• update supported node versions, migrate to use swagger-parser v8.0.0 and general bumps (6007c86)

BREAKING CHANGES

• There are two breaking changes in this release:

1. nodejs 6.x is not supported anymore

To migrate from older versions, please start using nodejs 8.x or above.

1. swagger-parser v8.0.0 is now used, which enforces specs to follow the official JSON Schemas for Swagger2 and OpenApi3

This change might cause errors where swagger-parser complains about specs being invalid. To migrate from older versions, please address any validation errors returned by this library. More information about this can be found here: https://github.com/APIDevTools/swagger-parser/blob/master/CHANGELOG.md

<a name="0.22.0"></a>