OpenAPI Specification Diff Tool

By Reuven Harrison

tl;dr oasdiff is a tool for comparing OpenAPI Specifications; also a Go module.

OpenAPI Specification (previously known as Swagger) is a standard for documenting REST APIs. Here’s a small example:

info:
title: Tufin
version: 1.0.0
openapi: 3.0.3
paths:
/api/audit:
get:
parameters:
- in: query
name: limit
required: true
schema:
description: Non-negative integers
example: '1000'
format: non-negative integer
pattern: '^(?:\d+)$'
type: integer
responses:
'200':
description: OK

While working with OpenAPI, we needed to track API changes. We found some diff tools but they ignored certain kinds of changes, for example, there was no indication of schema changes. So we decided to create oasdiff — a Go module for comparing OpenAPI Specifications.

You can use oasdiff to compare two versions of an OpenAPI spec using the oasdiff docker image, like this:

docker run --rm -t tufin/oasdiff -base https://raw.githubusercontent.com/Tufin/oasdiff/master/data/openapi-test1.yaml -revision https://raw.githubusercontent.com/Tufin/oasdiff/master/data/openapi-test3.yaml

oasdiff provides a comprehensive and deep comparison of the API specs, all the way down to their parameters, bodies and schemas, recursively. For example:

spec:
paths:
deleted:
- /subscribe
- /api/{domain}/{project}/install-command
- /register
modified:
/api/{domain}/{project}/badges/security-score:
operations:
added:
- POST
modified:
GET:
tags:
deleted:
- security
parameters:
deleted:
cookie:
- test
header:
- user
- X-Auth-Name
modified:
path:
domain:
schema:
type:
from: string
to: integer
format:
from: hyphen-separated list
to: non-negative integer
description:
from: Hyphen-separated list of lowercase string
to: Non-negative integers (including zero)
min:
from: null
to: 7
pattern:
from: ^(?:([a-z]+-)*([a-z]+)?)$
to: ^(?:\d+)$
query:
filter:
content:
schema:
properties:
modified:
color:
type:
from: string
to: number
image:
explode:
from: null
to: true
schema:
description:
from: alphanumeric
to: alphanumeric with underscore, dash, period, slash and colon
token:
schema:
anyOf: true
type:
from: string
to: ""
format:
from: uuid
to: ""
description:
from: RFC 4122 UUID
to: ""
pattern:
from: ^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12})$
to: ""
responses:
added:
- default
deleted:
- "200"
- "201"
parameters:
deleted:
path:
- domain
security:
deleted:
- bearerAuth
servers:
deleted:
- tufin.com
tags:
deleted:
- security
- reuven
components:
schemas:
deleted:
- rules
- network-policies
parameters:
deleted:
header:
- network-policies
headers:
deleted:
- testc
- new
- test
requestBodies:
deleted:
- reuven
responses:
deleted:
- OK
securitySchemes:
deleted:
- OAuth
- bearerAuth

To get a simplified text/markdown report add the format flag:

docker run --rm -t tufin/oasdiff -format text -base https://raw.githubusercontent.com/Tufin/oasdiff/master/data/openapi-test1.yaml -revision https://raw.githubusercontent.com/Tufin/oasdiff/master/data/openapi-test3.yaml

Or as HTML:

docker run --rm -t tufin/oasdiff -format html -base https://raw.githubusercontent.com/Tufin/oasdiff/master/data/openapi-test1.yaml -revision https://raw.githubusercontent.com/Tufin/oasdiff/master/data/openapi-test3.yaml

The text/markdown report looks like this:

### New Endpoints
-----------------
### Deleted Endpoints
---------------------
POST /register
POST /subscribe
### Modified Endpoints
----------------------
GET /api/{domain}/{project}/badges/security-score
* Modified cookie param: test
- Content changed
* Modified query param: filter
- Content changed
- Schema changed
* Modified query param: image
* Modified header param: user
- Schema changed
- Schema added
- Content changed
* Response changed
- New response: default
- Deleted response: 200
- Modified response: 201
- Content changed
- Schema changed
- Type changed from 'string' to 'object'
GET /api/{domain}/{project}/install-command
* Deleted header param: network-policies
* Response changed
- Modified response: default
- Description changed from 'Tufin1' to 'Tufin'
- Headers changed
- Deleted header: X-RateLimit-Limit

You can also embed oasdiff into your Go program like this:

d := diff.Get(&diff.Config{}, base, revision)

For a full example, see https://github.com/Tufin/oasdiff/blob/master/main.go

I hope you find it useful.

Reuven

From the Security Policy Company. This blog is dedicated to cloud-native topics such as Kubernetes, cloud security and micro-services.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store