When an API definition changes, a line-by-line file comparison can obscure what happened to endpoints and schemas. An API diff tool compares the before and after OpenAPI definitions and reports changes in terms of the OpenAPI document structure. This helps a team review an evolving design and identify changes that may affect existing consumers. section 4.2 section 4.3
Compare two definitions
Run `oasdiff diff api.yaml apiv2.yaml`. The default YAML report groups changes under nodes such as `paths` and `components`. In the example, it reports a deleted categories path, a modified products GET operation, added response headers, and a deleted response schema. A changed description appears as `from` and `to` values. 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
Inspect how `deleted` and `modified` entries locate changes within paths, operations, responses, and schemas. section 4.3
For a quick count, run `oasdiff summary api.yaml apiv2.yaml`; its output reports whether a diff exists and counts deleted or modified endpoints, paths, and schemas. For consumer-facing notes, run `oasdiff changelog api.yaml apiv2.yaml`. The example flags a path removed without deprecation as an `error` and a removed schema as `info`. Edit and supplement that output before publishing a changelog: a tool report is a starting point for communication, not the whole change-management policy. section 4.3 section 4.5
2 changes: 1 error, 0 warning, 1 info
error [api-path-removed-without-deprecation] at api.yaml
in API GET /v1/catalog/categories
api path removed without deprecation
info [api-schema-removed]
in components/schemas
removed the schema 'CategoriesResponse'
Compare the reported error and informational change before deciding what consumers need to know. section 4.5
Command-line diff tools can run in a CI/CD pipeline to check successive definitions. Decide which findings count as breaking changes in a published policy: a breaking change forces a consumer to update its client, and the policy should state the organization's breaking-change rules, version stability levels, and version schedule. section 4.3 section 4.13
