Utility to compare the Zeebe REST OpenAPI spec across branches of the Camunda repo.

It compares:

• old: stable/8.8 -> zeebe/gateway-protocol/src/main/proto/rest-api.yaml
• new: main -> multi-part spec under zeebe/gateway-protocol/src/main/proto/v2

It produces:

• a semantic OpenAPI diff (text/markdown/html/json) via OpenAPITools openapi-diff when available
• a “git diff”-style side-by-side HTML diff by bundling both specs and diffing the bundled JSON

• uv
• Python 3.14
• git
• Optional for semantic diffs:
  • openapi-diff (Homebrew) or Docker (to run openapitools/openapi-diff)

uv venv --python 3.14
source .venv/bin/activate
uv pip install -e .

camunda-openapi-diff diff --out-dir out

If the v2 entry file can’t be auto-detected, pass it explicitly:

camunda-openapi-diff diff --new-entry <relative/path/within/v2>

Written to --out-dir:

• openapi.diff.html (git-style, side-by-side)
• openapi.unified.diff (unified diff text)
• old.bundled.json, new.bundled.json
• If openapi-diff is available: semantic.diff.{txt,md,html,json}

To view a useful report, run npx http-serve out and look at the semantic.diff.html.