Catch breaking changes before they ship

A breaking change is one that makes existing clients fail: an endpoint removed, a field renamed, a parameter that is suddenly required. They are easy to make and easy to miss in review. swc diff finds them by reading your API straight from the source code; no running server or test data is needed.

It understands Python (FastAPI, Flask, Django), JavaScript and TypeScript (Express, NestJS, Next.js, Fastify, Koa, Hono, Elysia), PHP (Laravel, Symfony, Slim), Java and Kotlin (Spring, JAX-RS, Micronaut), Go, Rust, Ruby (Rails, Sinatra) and C# (ASP.NET Core).

Compare with the main branch

In your project folder:

swc diff --base origin/main

You get a list such as:

✗ BREAKING  GET /users  endpoint removed  (app.js:3)
! warning   POST /orders  new required field `currency`
+ info      GET /users/{id}/orders  endpoint added

Breaking changes are removed endpoints, new required fields and parameters, changed types, removed values and new sign-in requirements. Additions are listed as information. The command exits 1 when it finds breaking changes, so CI fails; change that with --fail-on warning, any or never.

Comment on the pull request

--format markdown writes a table for a pull-request comment. The CLI page has a ready GitHub Actions workflow that posts it on every pull request, and the runner's Run in CI dialog can add it for GitHub, GitLab and Jenkins.

See which requests to re-test

Add your collection and swc diff also lists the requests that call a changed endpoint:

swc diff --base origin/main --collection <collection-id>

Requests to re-test (1):
  GET /users  List users  (r-list)

To run exactly those, use swc run … --affected-since origin/main from the previous lesson.

Find undocumented and stale endpoints

Over time, the code, the API definition and the collection drift apart. swc inventory compares all three:

swc inventory . --spec openapi.yaml --collection <collection-id>

It lists:

• routes in the code but not in the API definition: undocumented ("shadow") endpoints that clients may find but nobody reviews;
• operations in the definition the code no longer has;
• routes in the code with no request in the collection, so nothing tests them;
• requests in the collection for routes that are gone.

Add --fail-on undocumented in CI to stop new undocumented endpoints from being merged.

The same comparison is in the app for public GitHub repositories: open a collection's Coverage tab, paste the repository (and the backend folder, if any) under Compare with code and click Scan and compare.

In the app: compare API definition versions

If you keep your API definition in APIs, every saved version can be checked the same way:

1. Open the API and go to Versions.
2. Pick an older version and switch to Breaking changes.

You get the changes from that version to the current definition, marked Breaking, Warning or Info with the same rules as swc diff, plus the response side, which code scans cannot see: a success status replaced, a response field removed or retyped (breaking), a field that may now be missing or a new enum value (warning). Rename price to total_price and it lists the tests and saved examples that still read price, so you can update them in the same change. If the API is linked to a collection, Requests to re-test lists the requests that call a changed endpoint, and Run these opens the collection runner with just those selected. Report downloads the list as Markdown for a pull request or release note.

What you learned

• swc diff --base origin/main reads the API from your code and fails CI on breaking changes.
• --collection lists the requests to re-test; swc inventory finds undocumented and stale endpoints.
• In the app, Versions → Breaking changes and Coverage → Compare with code do the same for API definitions and public repositories.

Next: keep your whole workspace in Git.