v1.9.0

Summary

This release adds comprehensive OpenAPI specification comparison and breaking change detection capabilities through the new differ package and diff CLI command.

What's New

🆕 Diff Command and Differ Package

Compare OpenAPI specifications to identify differences and detect breaking changes that could affect API consumers.

Features:

• Two operational modes:
  • Simple mode: Reports all semantic differences
  • Breaking mode: Categorizes changes by severity and identifies breaking changes
• Comprehensive change detection across all OAS elements
• Smart severity classification (Critical, Error, Warning, Info)
• Support for all OAS versions (2.0, 3.0.x, 3.1.x, 3.2.x)
• Cross-version comparison with limitations

CLI Usage

# Simple semantic diff
oastools diff api-v1.yaml api-v2.yaml

# Breaking change detection with severity classification
oastools diff --breaking api-v1.yaml api-v2.yaml

# Exclude informational changes from output
oastools diff --breaking --no-info old.yaml new.yaml

# Works with URLs too
oastools diff https://example.com/api/v1.yaml https://example.com/api/v2.yaml

API Usage

import "github.com/erraggy/oastools/differ"

// Simple convenience function
result, err := differ.Diff("api-v1.yaml", "api-v2.yaml")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Found %d changes\n", len(result.Changes))

// Breaking change detection
d := differ.New()
d.Mode = differ.ModeBreaking
d.IncludeInfo = false

result, err := d.Diff("api-v1.yaml", "api-v2.yaml")
if result.HasBreakingChanges {
    fmt.Printf("⚠️  Found %d breaking changes\n", result.BreakingCount)
    os.Exit(1)
}

Change Detection Categories

The differ detects changes across all OAS elements:

• ✅ Endpoints (paths)
• ✅ Operations (HTTP methods)
• ✅ Parameters
• ✅ Request bodies
• ✅ Responses
• ✅ Schemas/definitions
• ✅ Security schemes
• ✅ Servers
• ✅ Metadata (info, contact, license, tags)

Breaking Change Classification

In breaking mode, changes are categorized by severity:

• Critical 🚨: Removed endpoints, operations, required parameters
• Error ❌: Incompatible type changes, removed enum values, removed success responses
• Warning ⚠️: Deprecated operations, server changes, added required fields
• Info ℹ️: Additions, relaxed constraints, documentation updates

Output Features

• Pretty-printed output with severity symbols (✗, ⚠, ℹ)
• Changes grouped by category in breaking mode
• Summary statistics (total, breaking, warnings, info)
• Exit code 1 when breaking changes are found (perfect for CI/CD)

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools

Binary Download

Download the appropriate binary for your platform from the assets below.

Go Install

go install github.com/erraggy/oastools/cmd/oastools@v1.9.0

Related PRs

• #22 - feat(differ): add OpenAPI specification diff and breaking change detection

Technical Details

New Package:

• github.com/erraggy/oastools/differ - Public API for OpenAPI comparison

Implementation:

• differ/differ.go: Core types and API (266 lines)
• differ/simple.go: Simple semantic diff (742 lines)
• differ/breaking.go: Breaking change detection (814 lines)
• differ/doc.go: Package documentation (236 lines)
• differ/example_test.go: Runnable examples (154 lines)
• differ/differ_test.go: Comprehensive tests (300 lines)

Test Coverage:

• ✅ All existing tests pass
• ✅ Comprehensive unit tests for differ package
• ✅ Integration tests with real OAS examples
• ✅ Test fixtures: petstore-v1.yaml and petstore-v2.yaml

Documentation:

• ✅ Package-level godoc with examples
• ✅ CLI help text with usage examples
• ✅ Updated root package documentation
• ✅ Updated CLAUDE.md with differ package

Use Cases

Perfect for:

• 🔍 Reviewing API changes before deployment
• 🚨 Detecting breaking changes in CI/CD pipelines
• 📊 Generating changelogs between API versions
• ✅ Ensuring backward compatibility
• 📝 Documenting API evolution

Breaking Changes

None. This release is fully backward compatible.

Full Changelog

Full Changelog: v1.8.0...v1.9.0