OpenAPI Diff

> A CLI tool to identify differences between Swagger or OpenApi specifications.

Installation

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

``sh
npm install openapi-diff --save-dev
`

Description

This tool identifies what has changed between two Swagger or OpenApi specification files. These changes are classified into three groups, breaking, non-breaking and unclassified. Using an approach based on set theory this tool is able to calculate these differences to a high level of accuracy.

$3

SPEC_SUPPORT.md contains the details of what Swagger and OpenApi keywords are supported.

$3

Changes detected by this tool are classified into three groups.

#### Breaking

Changes that would make existing consumers incompatible with the API, for example:

- removing a path
- removing a method
- changing a property from optional to required in a request body
- changing a property from required to optional in a response body

#### Non Breaking

Changes that would not make existing consumers incompatible with the API, for example:

- adding a path
- adding a method
- changing a property from required to optional in a request body
- changing a property from optional to required in a response body

#### Unclassified

Changes that have been detected by the tool but can't be classified, for example:

- modifications to X-Properties

Usage

$3

Invoke the tool with a file path to the source specification file and the destination specification file. These files should be in JSON or YAML format and be valid Swagger 2 or OpenApi 3 specificaitons.

The tool will output a list of breaking, non breaking and unclassified differences found between the source and desitnation files.

If any breaking changes are found the tool will return a non-zero exit code.

##### Example

_/path/to/source-specification.yaml_

`yaml
openapi: 3.0.1
info:
title: User Service
version: 1.0.0
paths:
/users:
post:
requestBody:
content:
application/json:
schema:
properties:
name:
type: string
required:
- name
type: object
required: true
responses:
201:
description: Created
content:
application/json:
schema:
properties:
id:
type: string
required:
- id
type: object
/users/{userId}:
get:
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
200:
description: The user
content:
application/json:
schema:
properties:
name:
type: string
required:
- name
type: object
`

_/path/to/destination-specification.yaml_

`yaml
openapi: 3.0.1
info:
title: User Service
version: 1.0.0
paths:
/users:
post:
requestBody:
content:
application/json:
schema:
properties:
name:
type: string
required:
- name
type: object
required: true
responses:
201:
description: Created
content:
application/json:
schema:
properties:
id:
type: string
required:
- id
type: object
`

_Invoking the tool_

`sh
openapi-diff /path/to/source-specification.yaml /path/to/destination-specification.yaml
`

_Output_

Breaking changes found between the two specifications:

`json
{
"breakingDifferences": [
{
"type": "breaking",
"action": "remove",
"code": "path.remove",
"destinationSpecEntityDetails": [],
"entity": "path",
"source": "openapi-diff",
"sourceSpecEntityDetails": [
{
"location": "paths./users/{userId}",
"value": {
"get": {
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The user",
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"],
"type": "object"
}
}
}
}
}
}
}
}
]
}
],
"breakingDifferencesFound": true,
"nonBreakingDifferences": [],
"unclassifiedDifferences": []
}
`

$3

Invoke the library with a SpecOption for the source specification and the desitnation specification. A SpecOption has 3 properties:

| Name | Type | Required | Description |
| ---------: | :------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| content | string | Yes | A string containing the serialised json or yaml content of the specification. |
| location | string | Yes | A label for the specification, typically a file path or file name but can be any value. This is used when reporting errors parsing the specification content. |
| format | string | Yes | The format of the specification. Must be either swagger2 or openapi3 |

For full details of the nodejs api please refer to api-types.d.ts

#### Example

`javascript
const openapiDiff = require("openapi-diff");

const source = {
// openapi3...
};

const destination = {
// openapi3...
};

const result = await openapiDiff.diffSpecs({
sourceSpec: {
content: JSON.stringify(source),
location: "source.json",
format: "openapi3",
},
destinationSpec: {
content: JSON.stringify(destination),
location: "destination.json",
format: "openapi3",
},
});

if (result.breakingDifferencesFound) {
console.log("Breaking change found!");
}
``

Changelog

See CHANGELOG.md

Contributing

See CONTRIBUTING.md

License

See LICENSE.txt