API Diff — Changelog Generator#

Compare two OpenAPI/Swagger specs and generate a detailed changelog with breaking change detection.

Quick Diff#

bash

python3 scripts/api_diff.py old-spec.json new-spec.json

Output Formats#

bash

# Text (default)
python3 scripts/api_diff.py old.json new.json

# JSON
python3 scripts/api_diff.py old.json new.json --format json

# Markdown
python3 scripts/api_diff.py old.json new.json --format markdown

CI/CD Integration#

bash

# Fail if breaking changes found
python3 scripts/api_diff.py old.json new.json --fail-on-breaking
echo $?  # 0 = no breaking, 1 = breaking found

# Show only breaking changes
python3 scripts/api_diff.py old.json new.json --breaking-only

What It Detects#

Endpoint Changes#

ChangeBreaking?DescriptionEndpoint removedYesPath+method no longer existsEndpoint addedNoNew path+methodEndpoint deprecatedNoMarked as deprecated

Parameter Changes#

ChangeBreaking?DescriptionRequired param addedYesNew mandatory parameterOptional param addedNoNew optional parameterParam removed (required)YesRequired parameter removedParam type changedYesData type changedParam became requiredYesOptional → requiredParam became optionalNoRequired → optional

Schema Changes#

ChangeBreaking?DescriptionSchema removedYesDefinition removedRequired property addedYesNew mandatory fieldOptional property addedNoNew optional fieldProperty removedYesField removedProperty type changedYesData type changedEnum value removedYesAllowed value removedEnum value addedNoNew allowed value

Other Changes#

ChangeBreaking?DescriptionResponse code removedYesHTTP status no longer returnedResponse code addedNoNew HTTP statusSecurity changedYesAuth requirements changedServer URLs changedNoBase URL changedAPI version changedNoInfo version updated

Requirements#

• Python 3.6+
• No external dependencies (stdlib only)
• Input: JSON format OpenAPI 3.x or Swagger 2.0 specs