Add api-diff tool (runs locally + in PRs + HTML Report) - Supports OAS 3.1

.github/workflows/api-diff.yml

@@ -0,0 +1,69 @@
+name: OpenAPI Spec Diff Check
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Run branch logic unit tests
+      run: ./scripts/api-diff/api-diff.test.sh
+
+  api-diff:
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Make script executable
+      run: chmod +x scripts/api-diff/api-diff.sh
+
+    - name: Run API diff check
+      run: ./scripts/api-diff/api-diff.sh
+
+  html-reports:
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      contents: read
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Make script executable
+      run: chmod +x scripts/api-diff/api-diff.sh
+
+    - name: Generate HTML reports
+      run: ./scripts/api-diff/api-diff.sh --html-report
+
+    - name: Upload HTML reports
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: openapi-diff-reports
+        path: reports/
+        retention-days: 30

.gitignore

@@ -3,4 +3,7 @@
 node_modules
 
 # JetBrains generated files
-.idea
+.idea
+
+# Temporary files for API diff checks
+tmp/

README.md

@@ -29,6 +29,26 @@ Once you sign up or login, you can create a new API under your account and impor
 ## Updates
 If you find something missing or incorrect please [open an issue](https://github.com/XeroAPI/Xero-OpenAPI/issues/new) or send us a pull request.
 
+## API Diff Checking
+This repository includes automated API diff checking using [openapi-diff](https://github.com/OpenAPITools/openapi-diff) to detect breaking changes and modifications to the OpenAPI specifications.
+
+### Quick Start
+```bash
+# Check all xero*.yaml files against master branch
+./scripts/api-diff/api-diff.sh
+
+# Check a single file
+./scripts/api-diff/api-diff.sh xero_accounting.yaml
+```
+
+### Branch Naming Convention
+Branches containing `breaking` anywhere in the name will allow breaking changes without failing the build. All other branches will fail if breaking changes are detected.
+
+**Examples:** `breaking-api-v2`, `feature-breaking-change`, `api-breaking-update`
+
+### Full Documentation
+For detailed usage, configuration options, environment variables, and integration details, see [scripts/api-diff/README.md](scripts/api-diff/README.md).
+
 ## License
 
 This software is published under the [MIT License](http://en.wikipedia.org/wiki/MIT_License).

scripts/api-diff/README.md

@@ -0,0 +1,98 @@
+# API Diff Scripts
+
+This directory contains scripts for detecting and reporting API changes using [openapi-changes](https://pb33f.io/openapi-changes/).
+
+## Files
+
+### `api-diff.sh`
+Main script that compares OpenAPI specifications against the master branch.
+
+**Usage:**
+```bash
+# From the repo root
+./scripts/api-diff/api-diff.sh [--fail-on-breaking] [--html-report] [filename.yaml]
+
+# Check all xero*.yaml files
+./scripts/api-diff/api-diff.sh
+
+# Check a single file
+./scripts/api-diff/api-diff.sh xero_accounting.yaml
+
+# Fail on breaking changes (CI mode)
+./scripts/api-diff/api-diff.sh --fail-on-breaking
+
+# Generate HTML reports
+./scripts/api-diff/api-diff.sh --html-report
+```
+
+**Environment Variables:**
+- `OPENAPI_CHANGES_DOCKER_IMAGE` - Docker image to use (default: `pb33f/openapi-changes:latest`)
+- `BASE_BRANCH` - Branch to compare against (default: `origin/master`)
+
+### Comparing Different Branches
+
+By default, `api-diff.sh` compares your current branch against `origin/master`. You can compare against any other branch by setting the `BASE_BRANCH` environment variable:
+
+**Compare current branch against a different target branch:**
+```bash
+# Compare against origin/develop
+BASE_BRANCH=origin/develop ./scripts/api-diff/api-diff.sh
+
+# Compare against origin/main
+BASE_BRANCH=origin/main ./scripts/api-diff/api-diff.sh
+
+# Compare against a feature branch
+BASE_BRANCH=origin/feature/new-api ./scripts/api-diff/api-diff.sh
+
+# Compare specific file against different branch
+BASE_BRANCH=origin/v2-api ./scripts/api-diff/api-diff.sh xero-webhooks.yaml
+```
+
+**Compare two specific branches (advanced usage):**
+If you need to compare two arbitrary branches, you can temporarily switch to one branch and set BASE_BRANCH to the other:
+
+```bash
+# Compare feature-branch against develop
+git checkout feature-branch
+BASE_BRANCH=origin/develop ./scripts/api-diff/api-diff.sh
+
+# Compare main against a tag
+git checkout main
+BASE_BRANCH=v1.0.0 ./scripts/api-diff/api-diff.sh
+```
+
+### `api-diff.test.sh`
+Unit tests for the branch logic pattern matching used in GitHub Actions.
+
+**Usage:**
+```bash
+./scripts/api-diff/api-diff.test.sh
+```
+
+Tests validate that:
+- Branches containing `breaking` anywhere in the name are correctly identified
+- Other branches are handled with breaking change enforcement
+- All command-line flags (`--fail-on-breaking`, `--allow-breaking`, `--dry-run`, `--html-report`) are parsed correctly
+- Flag precedence and override behavior works as expected
+
+## Integration
+
+These scripts are integrated into the GitHub Actions workflow at `.github/workflows/api-diff.yml`:
+- **test-branch-logic** job - Runs unit tests
+- **api-diff** job - Runs API diff checks with conditional breaking change enforcement
+- **html-reports** job - Generates HTML reports and uploads them as artifacts
+
+### Branch Naming Convention
+The GitHub Actions workflow automatically adjusts its behavior based on branch names:
+
+**Allow Breaking Changes:**
+- Any branch containing `breaking` in the name
+- Examples: `breaking-api-v2`, `feature-breaking-change`, `api-breaking-update`
+- The `--fail-on-breaking` flag is NOT passed to the script
+
+**Fail on Breaking Changes:**
+- All other branches (main, master, develop, feature branches, etc.)
+- The `--fail-on-breaking` flag IS passed to the script
+- Build will fail if breaking changes are detected
+
+This allows developers to explicitly signal when they're working on breaking changes by including `breaking` in their branch name.