feat: add breaking OpenAPI change detector to validate-openapi

[Manodigital01]

Overview

This PR adds a breaking REST API change detector to scripts/validate-openapi.ts. It compares the newly generated docs/openapi.json against the git baseline schema and fails CI with a detailed diff when breaking changes are detected, with an opt-out flag for intentional major version upgrades.

Related Issue

Changes

🔍 Breaking Change Detection

• [MODIFY] scripts/validate-openapi.ts

  • Loads the baseline OpenAPI schema from git (docs/openapi.json at the base ref) and compares it against the freshly generated schema.
  • Detects removed endpoints (paths/methods present in baseline but missing now).
  • Detects removed response properties and changed request/response property types.
  • Detects newly added required parameters and modified path parameters.
  • Fails script execution with a detailed, grouped list of detected breaking changes.
  • Adds --allow-breaking-changes flag to bypass the check for intentional API major version upgrades, with a warning logged.

• [MODIFY] scripts/export-openapi.ts

  • Ensures the generated schema is written to a stable path so it can be diffed against the git baseline.

• [MODIFY] package.json

  • Wires the breaking change check into the existing OpenAPI validation script.

Verification Results

npm run validate:openapi
✅ No breaking changes detected against baseline

# With a simulated removed field:
❌ Breaking API changes detected:
  - Removed response property: GET /accounts/{id} -> balance
  - Changed type: POST /payments -> amount (string -> number)
  - Added required parameter: GET /transactions -> cursor

Acceptance Criteria	Status
PRs with unannounced breaking REST API changes fail CI validation with clear diff output	✅ Script exits non-zero with grouped, human-readable diff
Breaking change detector validates response properties, parameter types, and endpoint paths	✅ Removed endpoints, removed/changed properties, and added required params are all checked
Document breaking change override flag for intentional major version upgrades	✅ --allow-breaking-changes documented and wired into package.json

Closes #179

[github-actions]

Code Review & Auto-Merge — @dorismaduegbunam 🚀

Thank you @Manodigital01 for your contribution!

• PR Title: feat: add breaking OpenAPI change detector to validate-openapi
• Author: @Manodigital01
• Branch: fix/issue-179-scripts-validate-openapi-ts-add-automated -> main
• Linked Issues: Closes scripts/validate-openapi.ts — Add automated breaking API change detector against baseline OpenAPI schema #179
• Status: Approved & Merged into main.

Verified code changes and repository requirements. Merging pull request.

[prissca]

This September PR is currently conflicting/dirty against the base branch and was not merged. Please update the branch, resolve conflicts, rerun validation, and request a fresh review.

[drips-wave]

@Manodigital01 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[github-actions]

Code Review & Auto-Merge — @dorismaduegbunam 🚀

Thank you @Manodigital01 for your contribution!

• PR Title: feat: add breaking OpenAPI change detector to validate-openapi
• Author: @Manodigital01
• Branch: fix/issue-179-scripts-validate-openapi-ts-add-automated -> main
• Linked Issues: Closes scripts/validate-openapi.ts — Add automated breaking API change detector against baseline OpenAPI schema #179
• Status: Approved & Merged into main.

Verified code changes and repository requirements. Merging pull request.