diff-specs

Diff two OpenAPI specifications to identify breaking changes and migration steps.

5|5|Updated Nov 9, 2025

Search Tags:#versioning #openapi #migration #diff #breaking-changes #api-diff-tool

Ready to run

npx skills add https://github.com/erraggy/oastools --skill diff-specs

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: diff-specs
Source: https://github.com/erraggy/oastools/tree/main/plugin/skills/diff-specs
Command: npx skills add https://github.com/erraggy/oastools --skill diff-specs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Diff two OpenAPI specifications to identify breaking changes, categorize them by severity, and propose migration steps.

Core Features & Use Cases

Surface breaking changes between two API versions
Categorize changes by severity and generate migration guidance
Produce structured outputs to guide API evolution and client updates

Quick Start

Run the diff tool with the old version and the new version to generate a categorized changes report.

Frequently Asked Questions about diff-specs

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

FAQPage Schema

How do I find breaking changes between two OpenAPI specification versions?▼

To find breaking changes between two OpenAPI specification versions, you diff the old and new specs to surface modifications, categorize them by severity, and generate structured migration guidance for client updates.

What is the best way to categorize API breaking changes for migration planning?▼

Categorizing API breaking changes for migration planning involves diffing OpenAPI versions to identify severity levels, which produces structured outputs that guide API evolution and detail necessary client remediation steps.

How do I generate migration steps after updating an OpenAPI specification?▼

You generate migration steps after updating an OpenAPI specification by running a diff against the previous version, allowing the tool to identify breaking changes and propose structured remediation guidance for the transition.

Can I compare two OpenAPI specs to identify which API endpoints have breaking changes?▼

Yes, you can compare two OpenAPI specs to identify breaking changes by diffing the different versions of the same API, which surfaces and categorizes the specific modifications that require client updates.

Does the OpenAPI diff tool support paginated results for large specification files?▼

Yes, the OpenAPI diff tool supports paginated results, enabling you to systematically review categorized breaking changes and migration guidance when handling large specification files.

When do I need to diff OpenAPI specifications for breaking changes?▼

You need to diff OpenAPI specifications for breaking changes when comparing different versions of the same API, ensuring you surface any modifications that could impact existing clients and require structured migration steps.