API Contract Guard

API Contract Guard is a browser-based review workspace for comparing two OpenAPI 3.0 contracts before a release. It identifies supported breaking and compatible changes, explains their impact, and exports the review as JSON or Markdown.

Specifications are parsed locally in the browser and are not uploaded to a server.

Features

• Paste or upload JSON and YAML OpenAPI 3.0.x documents, up to 1 MB each.
• Compare previous and new contracts with endpoint- and operation-level findings.
• Filter breaking, warning, and compatible results.
• Inspect before-and-after values and technical locations on demand.
• Export complete reports as JSON or Markdown.
• Load a built-in example without external data.
• Review partial-analysis warnings separately from compatibility findings.

Requirements

• Node.js 22.13.0 or later.
• npm with support for lockfile version 3.
• Chromium installed through Playwright when running end-to-end tests.

Installation

Install the exact dependency tree recorded in the lockfile:

npm ci

For end-to-end tests, install the Playwright browser once:

npx playwright install chromium

Usage

Start the development server:

npm run dev

Open http://localhost:3000, then:

1. Paste or upload the previous specification.
2. Paste or upload the new specification.
3. Select Compare specifications.
4. Filter findings, expand technical details, or export the report.

Use Try with example to explore the workflow without providing files.

Supported compatibility rules

The comparison engine currently reports:

• Removed endpoints and HTTP operations.
• Added endpoints and HTTP operations as compatible changes.
• Added required parameters and parameters that became required.
• Removed parameters and request parameter type changes.
• Request bodies that became required.
• Added required request properties.
• Request and response schema or property type changes.
• Removed response status codes and response properties.
• Operation summary or description changes as compatible changes.

Path Item and Operation parameters are combined using OpenAPI override semantics. Internal component-schema references are resolved with circular-reference protection.

Known limitations

API Contract Guard is not proof of complete API compatibility. Version 1.0.0 does not fully analyze:

• Composed schemas using allOf, oneOf, or anyOf.
• External references or referenced request bodies.
• Security requirement changes, callbacks, polymorphism, and other unsupported OpenAPI features.
• OpenAPI 3.1 or earlier Swagger formats.

External references and schema composition produce explicit partial-analysis warnings. Review those warnings before treating a result as complete.

Privacy and security

Contract contents remain in the browser. The application has no server API, database, analytics integration, or required environment variables, and it does not automatically fetch external references.

Dependency audit status and the accepted development-only residual risk are documented in docs/SECURITY.md.

Quality checks

npm test
npm run lint
npm run build
npm run test:e2e
npm audit --omit=dev

The GitHub Actions workflow runs installation from the lockfile, unit tests, lint, a production build, and Playwright tests in Chromium.

Deployment to Vercel

Import the repository into a new Vercel project and keep the detected Next.js defaults. The production build command is npm run build; no environment variables, server APIs, database, or paid service is required.

Before deploying, run the quality checks above from a clean checkout. Do not add a deployment URL to this document until a real production deployment exists.

Architecture

src/lib/contracts contains framework-independent TypeScript for parsing, validation, reference handling, comparison, presentation data, and report generation. src/app, src/components, and src/hooks contain the Next.js interface and browser workflow.

License

Released under the MIT License.