This package provides utils and CLI to compute the diff between two swagger API specifications. Output diff can be configured according to version change.
- Identify breaking and smooth changes.
- Ensure API versioning consistency.
- Compute API changelogs.
- Prevent unexpected API changes.
Supports only swagger spec 2.0.
Install using npm:
npm install swagger-diffThe 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
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.
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.
Swagger-Diff defines rules that performs ONE type of diff checking. These rules are separated in 2 groups:
- breaking change
- smooth change
Examples:
- Delete path
- Rename path operationId
- Delete/Rename parametters
- Add a constraint on a parametter (like isRequired)
- Modify a response item
Examples:
- Add a path
- Add a param
- Add response item
- Add/Update descriptions
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
}
}
}3-error
2-warning
1-info
0-ignore
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
}
}
}To compute the diff, it exectutes a workflow composed of 4 main steps.
Resolve JSON references and dereference URIs.
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.
parameters are indexed by their name in order to allow raw-diff to compare parameters nicely.
deep-diff lib is used to compute deep raw diff.
Exectute each rule on each raw diff to output breakings and smooth changes.
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent