Apidiff
CLI tool that compares OpenAPI 3.0 specs and detects breaking changes across paths, parameters, schemas, and responses.
Overview
A Rust CLI for checking OpenAPI changes with direction-aware breaking-change detection that fits naturally into automated delivery pipelines.
Problem
API changes are easy to ship accidentally and difficult to reason about informally. A useful diff tool has to understand semantic compatibility, not just text differences, and it needs machine-friendly behavior for CI.
Approach
Apidiff parses OpenAPI 3.0 specs in JSON or YAML and evaluates compatibility across paths, operations, parameters, request bodies, responses, content types, and schemas. It reports breaking changes through intentional exit codes so it can fail builds automatically when needed.
Engineering Decisions
The most important design choices behind the project and why they matter.
Made compatibility checks direction-aware
The tool distinguishes between request-side and response-side changes because the same structural removal can be safe in one direction and breaking in another.
Covered multiple OpenAPI layers
It inspects seven parts of the spec so the result reflects contract compatibility rather than a narrow subset of path-level changes.
Used CI-friendly exit codes
Exit codes map directly to no changes, breaking changes, and errors, which makes the CLI easy to automate in release workflows.