openapi-schema-diff is a javascript library that compares two OpenAPI schemas and finds breaking changes.
npm install openapi-schema-diff
const compareOpenApiSchemas = require('openapi-schema-diff')
const sourceSchema = {
openapi: '3.0.0',
info: {
title: 'My API',
version: '1.0.0'
},
paths: {
'/pets': {
get: {
summary: 'Returns all pets',
responses: {
200: {
description: 'A list of pets.',
content: {
'application/json': {
schema: {
type: 'array',
items: {
type: 'object',
properties: {
name: {
type: 'string'
},
age: {
type: 'integer'
}
}
}
}
}
}
}
}
}
}
}
}
const targetSchema = {
openapi: '3.0.0',
info: {
title: 'My API',
version: '1.0.0'
},
paths: {
'/pets': {
get: {
summary: 'Returns all pets',
responses: {
200: {
description: 'A list of pets.',
content: {
'application/json': {
schema: {
type: 'array',
items: {
type: 'object',
properties: {
name: {
type: 'string'
},
age: {
type: 'integer'
},
breed: {
type: 'string'
}
}
}
}
}
}
}
}
}
}
}
}
const differences = compareOpenApiSchemas(sourceSchema, targetSchema)
assert.deepEqual(differences, {
isEqual: false,
sameRoutes: [],
addedRoutes: [],
deletedRoutes: [],
changedRoutes: [
{
method: 'get',
path: '/pets',
sourceSchema: sourceSchema.paths['/pets'].get,
targetSchema: targetSchema.paths['/pets'].get,
changes: [
{
type: 'responseBody',
statusCode: '200',
mediaType: 'application/json',
action: 'changed',
sourceSchema: sourceSchema.paths['/pets'].get.responses['200'].content['application/json'],
targetSchema: targetSchema.paths['/pets'].get.responses['200'].content['application/json'],
changes: [
{
keyword: 'schema',
changes: [
{
jsonPath: '#/items/properties/breed',
source: undefined,
target: {
type: 'string'
}
}
],
comment: 'response header schema has been changed'
}
],
comment: 'response body for "200" status code and "application/json" media type has been changed in GET "/pets" route'
}
]
}
]
})
Compares two OpenAPI schemas and returns and finds breaking changes. Source and target schemas must have the same OpenAPI major version.
sourceSchema
<object> - source OpenAPI schema.targetSchema
<object> - target OpenAPI schema.- Returns - an object with schema differences.
isEqual
<boolean> -true
if target schema does not have breaking changes,false
otherwise.sameRoutes
<array> - an array of routes that are present in both schemas and do not have breaking changes. See same route.addedRoutes
<array> - an array of routes that are present in target schema but not in source schema. See added route.deletedRoutes
<array> - an array of routes that are present in source schema but not in target schema. See deleted route.changedRoutes
<array> - an array of routes that are present in both schemas and have breaking changes. See changed route.
method
<string> - HTTP method name of the route.path
<string> - path of the route.sourceSchema
<object> - source OpenAPI schema of the route.targetSchema
<object> - target OpenAPI schema of the route.
method
<string> - HTTP method name of the route.path
<string> - path of the route.targetSchema
<object> - target OpenAPI schema of the route.
method
<string> - HTTP method name of the route.path
<string> - path of the route.sourceSchema
<object> - source OpenAPI schema of the route.
method
<string> - HTTP method name of the route.path
<string> - path of the route.sourceSchema
<object> - source OpenAPI schema of the route.targetSchema
<object> - target OpenAPI schema of the route.changes
<array> - a list of route components (header, querystring, body, ...) that have breaking changes. See change object
type
<string> - type of the component. One ofparameter
,requestBody
,responseBody
,responseHeader
.action
<string> - action that was performed on the component. One ofadded
,deleted
,changed
.sourceSchema
<object> - source OpenAPI schema of the component.targetSchema
<object> - target OpenAPI schema of the component.comment
<string> - a comment describing the change.changes
<array> - a list of changes in a component json schema. Exist only ifaction
equals tochanged
. Each schema keyword has it's own change object. See list of change objects.
Each of the route components has it's own unique properties that identify it. For more details look at the component change object: parameter, request body, response body, response header.
type
<string> - type of the component. Equals toparameter
.name
<string> - name of the parameter.in
<string> - location of the parameter. One ofquery
,header
,path
,cookie
.schemaChanges
- a list of changes in a component json schema. See schema change object.comment
<string> - a comment describing the change.
type
<string> - type of the component. Equals torequestBody
.mediaType
<string> - media type of the component.schemaChanges
- a list of changes in a component json schema. See schema change object.comment
<string> - a comment describing the change.
type
<string> - type of the component. Equals toresponseBody
.statusCode
<string> - HTTP status code of the component.mediaType
<string> - media type of the component.schemaChanges
- a list of changes in a component json schema. See schema change object.comment
<string> - a comment describing the change.
type
<string> - type of the component. Equals toresponseHeader
.header
<string> - name of the header.statusCode
<string> - HTTP status code of the component.schemaChanges
- a list of changes in a component json schema. See schema change object.comment
<string> - a comment describing the change.
keyword
<string> - keyword name. Equals toschema
.comment
<string> - a comment describing the change.changes
<array> - a list of changes in a component json schema.jsonPath
<string> - JSON path of the changed schema.source
<object> - source subschema placed at thejsonPath
.target
<object> - target subschema placed at thejsonPath
.
keyword
<string> - keyword name. Equals torequired
.source
<boolean> - source value of the keyword.target
<boolean> - target value of the keyword.comment
<string> - a comment describing the change.
MIT