Diff two OpenAPI YAML files and produce a backwards-compatibility changelog grouped into breaking, non-breaking, and additive changes.
Compares two OpenAPI documents (3.0 or 3.1) and generates a structured changelog grouped into Breaking, Non-Breaking, and Additive sections. Each entry cites the path, method, and JSON-pointer to the changed element.
old_spec: path to the previous OpenAPI YAML/JSON file.new_spec: path to the current OpenAPI YAML/JSON file.output_format: markdown (default) or json.npx @redocly/cli lint <old_spec> and the same for <new_spec>. Abort if either fails.oasdiff diff <old_spec> <new_spec> --format json > diff.json.oasdiff breaking <old_spec> <new_spec> --format json > breaking.json.[METHOD] /path - <change> (was: <old>, now: <new>).#/paths/~1users/get/responses/200/content/application~1json/schema/properties/age).MAJOR if any breaking entries, MINOR if any additive endpoints/fields, else PATCH.CHANGELOG-API.md or JSON to stdout per output_format.CHANGELOG-API.md with sections ## Breaking, ## Non-Breaking, ## Additive, plus a header listing the verdict and counts. JSON output mirrors the same shape with verdict, breaking[], non_breaking[], additive[] arrays.
Re-run oasdiff breaking and confirm the count of breaking entries equals the report's Breaking section row count. Sample-check three entries by reading the relevant paths.<route>.<method> block in both specs and confirming the diff statement is accurate. If oasdiff reports zero diffs but content hashes differ, surface a warning — that usually means whitespace-only changes which are fine to ignore.
swagger2openapi first, document the conversion in the report header.$ref cycles: resolve refs lazily; if a cycle prevents resolution, emit a cycle-detected note rather than crashing.x-*) changes: report under Non-Breaking with an "extension" tag.paths: {}: no comparison possible; exit with a "spec stub" warning.Other publishers' experience with this skill. Self-rating is blocked.
Sign in and publish to the registry to leave a rating.
No ratings yet. Be the first.
Same domains or capabilities as amitte/api-changelog-from-openapi-diff.
Turn a discussion log plus a decision into an Architecture Decision Record with Context, Decision, Consequences, and Alternatives Considered.
Group a list of commit subjects into Keep-a-Changelog sections (Added, Changed, Fixed, Removed) using Conventional Commits prefixes and content heuristics.
Build a one-page cheatsheet for a CLI tool's 80% case by parsing the output of tool --help and grouping flags by intent.
Document every env var declared in .env.example and config files, cross-referenced to the code locations that read each one.
Audit a CORS configuration for over-permissive Origin, Methods, and Headers and propose a tightened policy keyed to actual cross-origin call patterns.
Walk all markdown files in a repo, fetch every external link with HEAD, and report 4xx, 5xx, and redirect chains for cleanup.