skills.rest
epieczko
epieczkoCOMMUNITY
Explore all skills by this author →
GitHub

api.compatibility

Detect breaking changes between OpenAPI/Swagger specification versions.

2|Updated Oct 22, 2025
Search Tags:#api#openapi#validation#compatibility#breaking-changes
One-click install
npx skills add https://github.com/epieczko/betty --skill api-compatibility
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api.compatibility
Source: https://github.com/epieczko/betty/tree/main/skills/api.compatibility
Command: npx skills add https://github.com/epieczko/betty --skill api-compatibility

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Compares two API specifications and surfaces breaking and non-breaking changes to help maintain backward compatibility.

Core Features & Use Cases

  • Compares paths, schemas, and operations
  • Distills changes into breaking and non-breaking categories
  • Outputs a structured report for CI/CD decisions

Quick Start

python skills/api.compatibility/check_compatibility.py <old> <new>

Frequently Asked Questions about api.compatibility

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I detect breaking changes between API versions?▼

Breaking changes between API specifications are detected by comparing old and new OpenAPI/Swagger specs to identify endpoint removals, operation changes, schema modifications, and property alterations that affect backward compatibility. The compatibility checker analyzes paths, operations, schemas, parameters, and responses to produce a structured report categorizing changes.

What counts as a breaking change in an API spec?▼

Breaking changes include removed endpoints or operations, altered response schemas, removed or required parameters, and property modifications that clients depend on. Non-breaking changes like new endpoints or optional parameters are reported separately to distinguish safe updates from incompatible ones.

Can I use this with OpenAPI and Swagger specifications?▼

Yes, the compatibility checker applies to both OpenAPI and Swagger specifications. It reads two spec files as input and compares them to identify breaking and non-breaking changes across versions.

How do I integrate API compatibility checks into CI/CD?▼

Run the Python-based checker with old and new spec file paths as input to generate a structured compatibility report. The output includes compatible changes, breaking changes, non-breaking changes, and a change summary for automated CI/CD decision-making.

What output do I get from an API compatibility analysis?▼

The checker produces a structured report containing compatible items, breaking changes with details, non-breaking changes, and a summary. This enables downstream tooling to fail builds on incompatibilities or log changes for review.

Related Skills

Explore More Software Engineering Skills→
teexiiiteexiii

swagger

Serve interactive Swagger UI and raw OpenAPI spec from a TypeScript-based definition.

Community
Intermediate
cslsoftwarescslsoftwares

governance-refactoring-compatibility-policy

Map public consumers and enforce compatibility decisions before renaming symbols.

Community
Advanced
andregusman-raizandregusman-raiz
19

api-docs

Generate OpenAPI 3.1 specs and Markdown docs from code or existing specs.

Community
Advanced
mosheshammoshesham

api-design-reviewer

Lint OpenAPI specs for REST conventions and detect breaking changes.

Community
Advanced