Swiftpack.co - Package - mattpolzin/OpenAPIDiff


This is a WIP diffing library for OpenAPI documentation. It produces a hierarchical list of changes between two versions of an API. Only OpenAPI v3.x is supported.

By default, it uses the Foundation JSONDecoder which battle-tested but notably slow on Linux. You can save a lot of time by passing the --fast flag or running diffs on YAML files if the Yams parser does an adequate job of parsing your OpenAPI document.


To see an example of what this library produces when run against two YAML OpenAPI documents with the markdown option, take a look at the example folder.



The library ships with a very simple executable. If you just want to play with what you get out-of-the-box, the easiest option is to run the Docker image I host on Docker Hub.

The dockerized executable will require you to mount one or more volumes containing the versions of the API you wish to diff. Assuming you have the old and new versions of your API in the current working directory (named old.json and new.json), a simple invocation would be:

docker run --rm -v "$(pwd)/old.json:/api/old.json" -v "$(pwd)/new.json:/api/new.json" mattpolzin2/openapi-diff /api/old.json /api/new.json

You can pass mattpolzin2/openapi-diff the --markdown flag in addition to the two API document files to produce a markdown diff instead of the default plaintext diff.

You can pass mattpolzin2/openapi-diff the --fast flag to use faster (though less battle-tested) JSON parsing. The flag currently has no effect on YAML parsing.

For all options, see the --help.


As a library, you first reference this package from your manifest or pull it in via Xcode.

dependencies: [
  .package(url: "https://github.com/mattpolzin/OpenAPIDiff.git", .upToNextMinor(from: "0.2.0")),

Then you can produce diffs with

import OpenAPIKit
import OpenAPIDiff

let file1 = try Data(contentsOf: oldOpenAPIFile)
let file2 = try Data(contentsOf: newOpenAPIFile)

let api1 = try JSONDecoder().decode(OpenAPI.Document.self, from: file1)
let api2 = try JSONDecoder().decode(OpenAPI.Document.self, from: file2)

let comparison = api1.compare(to: api2)

let markdownDiff = comparison.markdownDescription
let plaintextDiff = comparison.description

By default you will be getting entries for all of the things that have not changed as well as those that have changed. You can easily omit the similarities with

let differences = comparison.description { !$0.isSame }
let markdownDifferences = comparison.markdownDescription { !$0.isSame }

The structure you are producing is ApiDiff. You can take a look at ApiDiff.swift if you want to operate on the diff in some way different than the description() and markdownDescription() methods do.

Building From Source

The library target (OpenAPIDiff) and executable target (openapi-diff) can both be built quite easily with either swift build or by opening the repository root folder in Xcode 11.

The docker image can be build from the included Dockerfile with

docker build -t openapi-diff .


Stars: 4

Used By

Total: 0


Switch all dependencies to using .git extension - 2020-09-09 14:14:40

Switch to Swift Package Manager dependency URLs that contain the .git extension. This is not required by SwiftPM, but if a project does not consistently use the .git extension on dependency URLs (or not) then SwiftPM can get into trouble. The majority of open source projects use or suggest using the .git extension, so this project will standardize in that direction as well.

Fast JSON parsing option - 2020-08-08 21:06:07

Adds the --fast flag that uses a faster less battle-tested parser to get substantial speed gains in Linux environments (like the Dockerized app).

Stable schema property sorting. - 2020-07-15 01:55:17

Updates to OpenAPIKit make the sorting of schema object required properties stable. This will make the schema diffing of this library/tool much more useful.

Add a bit of Security Scheme support - 2020-05-01 04:13:56

Update OpenAPIKit - 2020-04-22 07:12:23

Update OpenAPIKit, Update CLI, Add option to print stats - 2020-03-10 07:21:44

Now you can print help with openapi-diff --help. You can print stats (additions, removals, changes) with a --stats option.

Big improvements to how flattening is done. - 2020-02-18 07:10:59

Updates to OpenAPIKit - 2020-02-18 07:05:23

Just updates OpenAPIKit to take advantage of bug fixes and improvements.

More types are diffed, some nestings are collapsed - 2020-02-16 08:38:38

Added diffing on a number of additional OpenAPI components, including a "diff format" printout for schema diffs.

Flattened certain trivial nested changes (specifically where two nested changes in a row only contain one difference).

Added markdown support, Dockerized - 2020-02-15 20:18:24

Added markdown support and exposed on included executable as --markdown flag.



  • bind mount your two API JSON/YAML files to /api/old.yml and /api/new.yml
  • pass /api/old.yml /api/new.yml as arguments to docker container.
  • optionally pass --markdown to generate markdown instead of plaintext.

EXAMPLE: docker run -v ./old.yml:/api/old.yml -v ./new.yml:/api/new.yml mattpolzin2/openapi-diff /api/old.yml /api/new.yml

Juuuust a bit of diffing, but far from useless. - 2020-02-14 07:30:59

There is an executable target included for inspiration or just to build straight up for a super simple diffing utility.