feat: move to another tool supporting OAS 3.1 with nicer reporting

Author: rpocklin

.github/workflows/api-diff.yml

@@ -12,7 +12,7 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  test-branch-logic:
+  test:
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -25,7 +25,7 @@ jobs:
 
   api-diff:
     runs-on: ubuntu-latest
-    needs: test-branch-logic
+    needs: test
     permissions:
       contents: read
       pull-requests: write
@@ -40,4 +40,30 @@ jobs:
       run: chmod +x scripts/api-diff/api-diff.sh
 
     - name: Run API diff check
-      run: ./scripts/api-diff/api-diff.sh
+      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

scripts/api-diff/README.md

@@ -1,6 +1,6 @@
 # API Diff Scripts
 
-This directory contains scripts for detecting and reporting API changes using [openapi-diff](https://github.com/OpenAPITools/openapi-diff).
+This directory contains scripts for detecting and reporting API changes using [openapi-changes](https://pb33f.io/openapi-changes/).
 
 ## Files
 
@@ -10,7 +10,7 @@ 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] [filename.yaml]
+./scripts/api-diff/api-diff.sh [--fail-on-breaking] [--html-report] [filename.yaml]
 
 # Check all xero*.yaml files
 ./scripts/api-diff/api-diff.sh
@@ -20,10 +20,13 @@ Main script that compares OpenAPI specifications against the master branch.
 
 # 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_DIFF_DOCKER_IMAGE` - Docker image to use (default: `openapitools/openapi-diff:latest`)
+- `OPENAPI_CHANGES_DOCKER_IMAGE` - Docker image to use (default: `pb33f/openapi-changes:latest`)
 - `BASE_BRANCH` - Branch to compare against (default: `origin/master`)
 
 ### `api-diff.test.sh`
@@ -43,6 +46,7 @@ Tests validate that:
 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:

scripts/api-diff/api-diff.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Script to check API diffs using openapi-diff
-# Usage: ./scripts/api-diff/api-diff.sh [--fail-on-breaking] [filename.yaml]
+# Script to check API diffs using openapi-changes
+# Usage: ./scripts/api-diff/api-diff.sh [--fail-on-breaking] [--html-report] [filename.yaml]
 # Assumes you have Docker installed and the repo is checked out with master branch available
 
 set -e  # Exit on error
@@ -11,19 +11,22 @@ set -o pipefail  # Catch errors in pipes
 cd "$(dirname "$0")/../.."
 
 # Configuration
-DOCKER_IMAGE="${OPENAPI_DIFF_DOCKER_IMAGE:-openapitools/openapi-diff:latest}"
+DOCKER_IMAGE="${OPENAPI_CHANGES_DOCKER_IMAGE:-pb33f/openapi-changes:latest}"
 BASE_BRANCH="${BASE_BRANCH:-origin/master}"
 
 FAIL_ON_BREAKING=false
 TARGET_FILE=""
 DRY_RUN=false
+HTML_REPORT=false
 
 # Parse arguments
 for arg in "$@"; do
     if [ "$arg" = "--fail-on-breaking" ]; then
         FAIL_ON_BREAKING=true
     elif [ "$arg" = "--dry-run" ]; then
         DRY_RUN=true
+    elif [ "$arg" = "--html-report" ]; then
+        HTML_REPORT=true
     elif [[ "$arg" == *.yaml ]]; then
         TARGET_FILE="$arg"
     fi
@@ -112,21 +115,30 @@ for file in $files; do
         continue
     fi
 
-    # Run openapi-diff to check for changes and breaking changes
-    echo "--- API Diff ---"
-    set +e
-    DIFF_OUTPUT=$(docker run --rm -v "$(pwd)":/current -v "$TEMP_DIR":/base "$DOCKER_IMAGE" /base/"$file" /current/"$file" --fail-on-incompatible 2>&1)
-    DIFF_EXIT=$?
-    set -e
-    
-    echo "$DIFF_OUTPUT"
-    
-    if [ $DIFF_EXIT -eq 0 ]; then
-        echo "✓ No breaking changes detected"
+    # Run openapi-changes
+    if [ "$HTML_REPORT" = true ]; then
+        echo "--- Generating HTML Report ---"
+        # Create reports directory if it doesn't exist
+        mkdir -p reports
+        REPORT_FILE="reports/${file%.yaml}-diff.html"
+        docker run --rm -v "$(pwd)":/current -v "$TEMP_DIR":/base "$DOCKER_IMAGE" html-report /base/"$file" /current/"$file" > "$REPORT_FILE"
+        echo "✓ HTML report generated: $REPORT_FILE"
     else
-        echo "⚠ Breaking changes detected (exit code: $DIFF_EXIT)"
-        BREAKING_CHANGES_FOUND=true
-        FILES_WITH_BREAKING_CHANGES+=("$file")
+        echo "--- API Diff ---"
+        set +e
+        DIFF_OUTPUT=$(docker run --rm -v "$(pwd)":/current -v "$TEMP_DIR":/base "$DOCKER_IMAGE" summary --no-logo --no-color /base/"$file" /current/"$file" 2>&1)
+        DIFF_EXIT=$?
+        set -e
+        
+        echo "$DIFF_OUTPUT"
+        
+        if [ $DIFF_EXIT -eq 0 ]; then
+            echo "✓ No breaking changes detected"
+        else
+            echo "⚠ Breaking changes detected (exit code: $DIFF_EXIT)"
+            BREAKING_CHANGES_FOUND=true
+            FILES_WITH_BREAKING_CHANGES+=("$file")
+        fi
     fi
 
     PROCESSED_FILES=$((PROCESSED_FILES + 1))
@@ -139,7 +151,15 @@ echo "Processed: $PROCESSED_FILES/$TOTAL_FILES files"
 echo "========================================"
 
 # Summary
-if [ "$BREAKING_CHANGES_FOUND" = true ]; then
+if [ "$HTML_REPORT" = true ]; then
+    echo ""
+    echo "📊 HTML reports generated:"
+    if [ -d "reports" ]; then
+        ls -la reports/
+    else
+        echo "No reports directory found"
+    fi
+elif [ "$BREAKING_CHANGES_FOUND" = true ]; then
     echo ""
     echo "❌ Breaking changes detected in the following files:"
     for file in "${FILES_WITH_BREAKING_CHANGES[@]}"; do

scripts/api-diff/test-api-diff.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Script to check API diffs using openapi-diff
+# Script to check API diffs using openapi-changes
 # Usage: ./scripts/api-diff/test-api-diff.sh [--fail-on-breaking] [filename.yaml]
 # Assumes you have Docker installed and the repo is checked out with master branch available
 
@@ -11,7 +11,7 @@ set -o pipefail  # Catch errors in pipes
 cd "$(dirname "$0")/../.."
 
 # Configuration
-DOCKER_IMAGE="${OPENAPI_DIFF_DOCKER_IMAGE:-openapitools/openapi-diff:latest}"
+DOCKER_IMAGE="${OPENAPI_CHANGES_DOCKER_IMAGE:-pb33f/openapi-changes:latest}"
 BASE_BRANCH="${BASE_BRANCH:-origin/master}"
 
 FAIL_ON_BREAKING=false
@@ -87,38 +87,22 @@ for file in $files; do
         continue
     fi
 
-    # Note: openapi-diff provides deterministic results for change detection.
+    # Note: openapi-changes provides deterministic results for change detection.
     # Both error and warning counts are consistent between runs.
 
-    # Run openapi-diff changelog
-    echo "--- Changelog ---"
+    # Run openapi-changes summary
+    echo "--- API Diff Summary ---"
     set +e
-    CHANGELOG_OUTPUT=$(docker run --rm -v "$(pwd)":/current -v "$TEMP_DIR":/base "$DOCKER_IMAGE" changelog --include-path-params /base/"$file" /current/"$file" 2>&1)
-    CHANGELOG_EXIT=$?
+    SUMMARY_OUTPUT=$(docker run --rm -v "$(pwd)":/current -v "$TEMP_DIR":/base "$DOCKER_IMAGE" summary /base/"$file" /current/"$file" 2>&1)
+    SUMMARY_EXIT=$?
     set -e
 
-    echo "$CHANGELOG_OUTPUT"
+    echo "$SUMMARY_OUTPUT"
 
-    if [ $CHANGELOG_EXIT -eq 0 ]; then
-        echo "✓ Changelog generated successfully"
-    else
-        echo "⚠ Could not generate changelog (exit code: $CHANGELOG_EXIT)"
-    fi
-    
-    # Run breaking changes check
-    echo ""
-    echo "--- Breaking changes check ---"
-    set +e
-    BREAKING_OUTPUT=$(docker run --rm -v "$(pwd)":/current -v "$TEMP_DIR":/base "$DOCKER_IMAGE" breaking --fail-on ERR --include-path-params /base/"$file" /current/"$file" 2>&1)
-    BREAKING_EXIT=$?
-    set -e
-    
-    echo "$BREAKING_OUTPUT"
-    
-    if [ $BREAKING_EXIT -eq 0 ]; then
+    if [ $SUMMARY_EXIT -eq 0 ]; then
         echo "✓ No breaking changes detected"
     else
-        echo "⚠ Breaking changes detected (exit code: $BREAKING_EXIT)"
+        echo "⚠ Breaking changes detected (exit code: $SUMMARY_EXIT)"
         BREAKING_CHANGES_FOUND=true
         FILES_WITH_BREAKING_CHANGES+=("$file")
     fi