OpenAPI Diff Tool — Detect Every Change, Automatically

Manually comparing two versions of an OpenAPI specification is not only tedious but also highly error-prone. As APIs evolve, their specifications can grow to thousands of lines, with complex interdependencies managed through $ref components. A simple text-based diff, like the one you might see in a Git commit, is insufficient because it fails to understand the semantic meaning of the OpenAPI structure.

Automated tooling is essential for managing this complexity. A purpose-built OpenAPI diff tool doesn't just compare text; it parses the specification, resolves all references, and understands the hierarchical structure of the API contract. For example, changing a property from optional to required within a referenced schema is a significant breaking change, but it might appear as a minor, one-word alteration in a text file.Without an automated, semantically-aware diff, teams risk shipping breaking changes unknowingly.

CI/CD Pipelines

By incorporating CodeRifts into your Continuous Integration and Continuous Deployment (CI/CD) pipeline, you can automatically fail builds that introduce high-risk or unauthorized breaking changes. You can use our CLI or REST API to add a diff check as a required step in your deployment workflow.

Pre-Merge Checks

With the CodeRifts GitHub App, every pull request that modifies an OpenAPI file gets an automatic check. A detailed comment is posted directly on the PR, showing a summary of the changes and a link to the full diff report. This enables developers and reviewers to understand the impact of their changes before they are merged.

API Versioning Strategy

Automated diffing is fundamental to a sound API versioning strategy. By understanding the nature of every change, you can make deliberate decisions about when to release a new minor version (for non-breaking, backward-compatible changes) versus a new major version (for breaking changes).

Migration from Swagger to OpenAPI 3.x

Upgrading a legacy Swagger 2.0 specification to OpenAPI 3.0 or 3.1 can be a complex process with many potential pitfalls. Using the CodeRifts diff tool, you can compare your old Swagger file with the newly converted OpenAPI 3.x file to verify that the API's contract has not been unintentionally altered during the migration.

Send two specs to the zero-auth endpoint and get a single structured verdict back — no signup, no key:

curl -s -X POST https://app.coderifts.com/api/v1/demo \
  -H "Content-Type: application/json" \
  -d '{"old_spec": "<your previous OpenAPI>", "new_spec": "<your current OpenAPI>"}'

The response includes decision (ALLOW / WARN / BLOCK), risk_score, safe_for_agent, the detected breaking-change patterns, and the reflex triggers that escalated the decision. One call, one machine-readable answer.

To turn that verdict into a one-line guardrail inside an agent, use the zero-config decorator. It has no dependencies beyond the Python standard library, it is framework-agnostic (LangGraph, AutoGen, or a plain function), and it caches the verdict per spec pair:

from coderifts_guard import coderifts_guard, CodeRiftsBlocked

@coderifts_guard(old_spec=previous_openapi, new_spec=current_openapi)
def run_agent_step(payload):
    # Runs only if CodeRifts does not return BLOCK.
    # On BLOCK it raises CodeRiftsBlocked before any side effect.
    return call_downstream_api(payload)

If the change would break a downstream contract, the decorator raises CodeRiftsBlocked and the agent halts before the unsafe call runs. The full runnable reference implementation — decorator plus an explicit LangGraph guard node — is public at github.com/coderifts/example-langgraph-guard.

Point any MCP client at the hosted endpoint and authenticate with a Bearer API key:

{
  "mcpServers": {
    "coderifts": {
      "url": "https://app.coderifts.com/mcp",
      "headers": { "Authorization": "Bearer <YOUR_CODERIFTS_API_KEY>" }
    }
  }
}

The agent gets governance tools natively, including preflight_check (full diff plus risk score, blast radius, incident cost, and an ALLOW / WARN / REQUIRE_APPROVAL / BLOCK decision), mcp_diff (compare two MCP manifests for breaking changes), and agent_tool_check (detect whether an API change breaks agent tool calling). Every tool returns the same Decision Spec v1.0 envelope (decision, risk_score, safe_for_agent, breaking_changes, patterns), so the agent can branch on a stable contract.

The endpoint is Streamable HTTP (protocol 2025-06-18) and is listed on the Official MCP Registry as io.github.coderifts/api-governance. For a one-click connect, the full tool list, and a copy-paste config, see the machine-readable page at coderifts.com/for-agents, or the MCP manifest.