Quick answer: When Cursor edits the OpenAPI file in a branch, review the spec diff as a contract change, not as text. Look first for breaking changes, removed or renamed paths and fields, tightened constraints, and altered security schemes, then check that each documented change matches what the service actually does. A lint-clean YAML file only proves the document is valid, so confirm the edited contract against real responses before you merge.
Why a spec diff is not a code diff
The spec is the shared contract, so a change to it reaches every consumer that reads the file: generated clients, mocks, docs, gateways, and the teams that build against the API. A removed field or a renamed path can compile fine in the producer repo and still break a client that is not in this pull request. That is why the review starts from the blast radius of the change rather than from line count. A two-line edit to a required field can matter more than a hundred lines of description rewrites, and large formatting changes can hide the one operation that actually changed behavior.
What counts as a breaking change
| Change in the spec | Breaking | Review action |
|---|---|---|
| Remove or rename a path or operation | Yes | Keep the old route, add deprecation, notify consumers |
| Remove a response field or change its type | Yes | Retain the field, version the change |
| Add a required field or narrow an enum | Yes | Make it optional first, widen rather than narrow |
| Change auth or a security scheme | Yes | Verify every client can still authenticate |
| Add an optional field or a new endpoint | No | Confirm the implementation exists |
| Rewrite a description or reorder keys | No | Check no semantic edit slipped in |
How to read the diff on the pull request
Raw YAML diffs are noisy because indentation, anchors, and key reordering change many lines at once. Prefer a structural diff that parses the old and new spec and compares the resolved operations, so a moved field does not look like a deletion. Read the rendered operation on both sides, then trace each changed path back to the code that handles it. If the editor changed the spec to match existing code, ask whether the contract should follow the code or the code should follow the contract; silently editing the spec to make a mismatch disappear just moves the breakage to clients. Treat the spec as a protected file and require a second review on changes to it.
Before removing anything, search the wider codebase and any known client repos for the operation or field, and check gateway logs for real traffic on it. A field with no reference in this repository may still be read by an external team. If the removal has to ship, mark the operation deprecated in one release and remove it in the next, and record the change in the API version history so consumers can plan instead of discovering the break at runtime.
Honest limits
Automated breaking-change detection helps but does not catch everything, because some contract changes are semantic rather than structural, and each tool has its own rules. A passing validation run means the document is well formed, not that the running service matches it, and editing the spec never deploys or alters the backend. Before merge, drive the edited contract against the real service. A desktop tool such as Powerduck can import the updated spec and run ordered scenario assertions through its local main process, checking status and response fields so the documented change is confirmed against live answers, while its AI review raises suspicions rather than proving the contract correct. For a wider look at how the editor compares with that workflow, see the comparison hub.
Frequently asked questions
Is adding a required field a breaking change? Yes for request bodies if clients must now send it, and it can break response validation too; add it as optional first, then make it required in a later version.
Will a spec validator catch breaking changes? It catches malformed structure, not the impact on consumers; use a dedicated OpenAPI diff and a human review for that judgment.
Should I let the AI edit the spec to match the code? Only after deciding which side is correct; auto-editing the contract to hide a mismatch pushes the break to clients, so keep the spec protected.
The bottom line
A spec diff on a pull request is a contract decision with a blast radius beyond the repo. Rank breaking changes first, use a structural diff to see through YAML noise, and confirm the edited document against the real service because a lint pass proves nothing about runtime. Treat the OpenAPI file as protected, and the AI's edits to it deserve the same scrutiny as a hand-written change.
Comments
Join the discussionNo comments yet. Be the first to comment.

