openapi-diff
Advanced tools
A CLI tool to identify differences between Swagger or OpenApi specifications.
Install the tool using npm and add it to the package.json
npm install openapi-diff --save-dev
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.
SPEC_SUPPORT.md contains the details of what Swagger and OpenApi keywords are supported.
Changes detected by this tool are classified into three groups.
Changes that would make existing consumers incompatible with the API, for example:
Changes that would not make existing consumers incompatible with the API, for example:
Changes that have been detected by the tool but can't be classified, for example:
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.
/path/to/source-specification.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
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
openapi-diff /path/to/source-specification.yaml /path/to/destination-specification.yaml
Output
Breaking changes found between the two specifications:
{
"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": []
}
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
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!')
}
See CHANGELOG.md
See CONTRIBUTING.md
See LICENSE.txt
FAQs
A CLI tool to identify differences between Swagger/OpenAPI specs.
The npm package openapi-diff receives a total of 22,595 weekly downloads. As such, openapi-diff popularity was classified as popular.
We found that openapi-diff demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.