https://github.com/pactflow/openapi-pact-comparator
https://github.com/pactflow/openapi-pact-comparator
open-source pactflow
Last synced: 29 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/pactflow/openapi-pact-comparator
- Owner: pactflow
- License: mit
- Created: 2024-01-29T07:11:01.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-05-27T08:20:18.000Z (about 1 month ago)
- Last Synced: 2026-05-27T10:15:33.943Z (about 1 month ago)
- Topics: open-source, pactflow
- Language: TypeScript
- Size: 1.89 MB
- Stars: 8
- Watchers: 7
- Forks: 4
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI-Pact-Comparator
## What is this?
This compares OpenAPI schemas and Pact contracts to determine if they are
compatible. It is inspired by
[swagger-mock-validator](https://github.com/pactflow/swagger-mock-validator)
and aims to retain a mostly compatible interface.
## Why rewrite it?
[swagger-mock-validator](https://github.com/pactflow/swagger-mock-validator)
has aged, and is very difficult to extend and improve on.
It is also very slow primarily due to inefficient use of
[ajv](https://ajv.js.org/); schemas are unnecessarily recompiled everytime
instead of being cached.
## How is this better?
**Schemas are compiled once, and reused where possible**. In practical terms,
this gives us an improvement exceeding 20x in real-world comparisons. In some
cases, this was 50x faster!
**Referenced schemas are NOT inlined**. They are kept as references to keep the
size of complex schemas down. We need to do this anyway to support circular
references. Further, unused references are skipped to speed up schema
compilation in AJV.
**Multiple pacts can be compared in one invocation to maximise schema reuse**.
Instead of performing the comparison per pair of OAS + Pact, we can reuse the
compiled OAS schemas across multiple Pacts.
**A fast HTTP router is used to match provider routes**. Instead of iterating
through an array of routes, we use [Radix
Tree](https://en.wikipedia.org/wiki/Radix_tree) search using
[find-my-way](https://github.com/delvedor/find-my-way) This allows large
providers to be traversed quickly.
**Computation is broken up to small units using async generators**. This leads
to low event loop delays, suitable for high concurrency servers.
## Usage
With error handling omitted for brevity:
```
import { Comparator } from "openapi-pact-comparator";
// openapi is object from JSON.parse() or yaml.load()
const comparator = new Comparator(openapi);
// pacts is array of objects the same way
for (const pact of pacts) {
for await (const result of comparator.compare(pact)) {
console.log(result);
}
}
```
## Quirks mode
To retain compatibility with
[swagger-mock-validator](https://github.com/pactflow/swagger-mock-validator),
an environment variable `QUIRKS` can be set [to any value]. When this is true,
all of SMV quirks are reproduced in case you are unable to migrate immediately.
The quirks can also be enabled/disabled by adding to the `info` section of the
OAS some extensions in the form of `x-opc-config-${quirk-name}`, where quirks
are listed [here](./src/utils/config.ts).
This mode may be removed eventually, so you should always endeavour to try to
update your comparisons to use the latest functionality.