llms.txt

# openapi-breaking-diff

> Compare two OpenAPI 3 documents and categorize changes as breaking or non-breaking, with JSON paths.

This library takes two OpenAPI 3 documents as plain parsed objects (you load the JSON yourself — no
file I/O or fetching inside the library) and diffs them: removed paths/methods, new required
parameters, removed response fields (via recursive schema walk), type changes, and narrowed enums
are BREAKING; added optional parameters/fields, new endpoints, widened enums, and description
changes are NON-BREAKING. Every change carries a JSON path pointing at exactly where it occurred,
plus a CI-friendly exit-code helper.

## API

- `diffOpenApi(oldDoc: OpenApiDocument, newDoc: OpenApiDocument): DiffResult`
- `checkBreaking(oldDoc: OpenApiDocument, newDoc: OpenApiDocument): { exitCode: 0 | 1; result: DiffResult }`
- Types: `OpenApiDocument`, `PathItemObject`, `OperationObject`, `ParameterObject`, `RequestBodyObject`, `ResponseObject`, `MediaTypeObject`, `SchemaObject`, `Change`, `ChangeCategory`, `DiffResult`

## Install

```
npm install @ferrow/openapi-breaking-diff
```

Part of the Ferrow open-source toolkit: https://github.com/FerrowAI/ferrow-toolkit — sponsored by https://ferrow.ai