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>"}'

This is the zero-auth POST /api/v1/demo surface, not MCP authorize. The demo body includes decision (ALLOW / WARN / BLOCK) as explanation. Agents that need permission must call authorize and branch on execution_action (CONTINUE | CONTINUE_WITH_MONITORING | REQUEST_APPROVAL | STOP).

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:

# coderifts_decorator.py is vendored from github.com/coderifts/agent-guard
# (examples/langgraph-guard-python/) — it is not published on PyPI; copy the file in.
from coderifts_decorator 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 an archived historical sample (last updated 2026-08-25); the maintained middleware is agent-guard. The sample is 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: preflight_change_set returns the Decision Spec governance envelope — branch on execution_action (CONTINUE | CONTINUE_WITH_MONITORING | REQUEST_APPROVAL | STOP; unrecognised values fail closed). decision (ALLOW / WARN / REQUIRE_APPROVAL / BLOCK) is explanation, not the branch key. verify_receipt returns a receipt-verification result (valid, status, currently_authorized); get_decision_details returns a stored decision envelope plus retrieval metadata. The three tools do not share one response shape. Additional governance operations are available over the separate REST API.

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.