Changing an OpenAPI definition can disrupt existing clients. Removing a path, for example, leaves consumers calling that endpoint with a 404 response. oasdiff compares the before and after definitions so teams can inspect changes, check for breaking changes, and prepare consumer-facing release notes. section 4.3 section 4.4
Run `oasdiff diff api.yaml apiv2.yaml` for a detailed comparison. Its default YAML output follows the OpenAPI object hierarchy: `paths` and `components` contain changes classified as `added`, `deleted`, or `modified`. Run `oasdiff summary api.yaml apiv2.yaml` when counts are enough for an initial review. section 4.3
paths:
deleted: #1
- /v1/catalog/categories
modified:
/v1/catalog/products:
operations:
modified:
GET:
description: #2
from: List all products.
to: List all products in Acme's catalog.
responses:
modified:
"200":
headers: #3
added:
- x-rate-limit-hour
- x-rate-limit-remaining
…
components:
schemas:
deleted: #1
- CategoriesResponse
The detailed diff identifies a deleted categories path and schema, then locates a modified GET operation’s description and added response headers. A change appearing in the diff is not, by itself, a judgment that clients will break. section 4.3 section 4.4
To check compatibility, run `oasdiff breaking api.yaml apiv2.yaml`. The reported error `api-path-removed-without-deprecation` identifies the deleted `GET /v1/catalog/categories` path as a breaking change. Add `--format json` when a machine-readable finding is needed; its fields include the rule ID, operation, path, and source definition. section 4.4
1 breaking changes: 1 error, 0 warning
error [api-path-removed-without-deprecation] at
original_source=api.yaml
in API GET /v1/catalog/categories
api path removed without deprecation
Read the first line as the finding count and severity, then the rule ID and operation as the reason and location. Here, one path removal produces one error. section 4.4
Review the release context before enforcing a finding. Removing an endpoint after a notified deprecation window is still a breaking change, but an organization may choose to handle that planned sunset differently. A deprecated operation can be marked `deprecated: true` and given an `x-sunset` date in its definition. section 4.4
Run `oasdiff changelog api.yaml apiv2.yaml` to obtain a starting point for an API changelog. Its example output marks the removed path as an error and the removed schema as informational. Edit, format, and supplement that output before publishing it to consumers; automated findings do not replace an explanation of what they need to change. section 4.5 section 4.4
