openapi-diff
This skill should be used when analyzing differences between two OpenAPI/Swagger spec versions, comparing API specifications, detecting breaking changes in APIs, generating API changelogs, or analyzing source code changes for API definitions. Triggers: "compare OpenAPI", "API diff", "spec changes", "breaking changes", "API changelog", "controller changes", "DTO changes", "API changes"
When & Why to Use This Skill
The OpenAPI Diff skill is a specialized developer tool designed to automate the analysis and comparison of OpenAPI/Swagger specifications. It proactively identifies breaking changes, tracks modifications in endpoints, schemas, and parameters, and generates detailed API changelogs from both spec files and source code to ensure seamless API evolution and backward compatibility.
Use Cases
- Automated Breaking Change Detection: Identify critical updates such as endpoint removals, new required parameters, or type changes before they impact downstream consumers.
- API Version Comparison: Compare different versions of swagger.json or openapi.yaml files to visualize structural differences and schema updates during the development lifecycle.
- Source Code Impact Analysis: Analyze git diffs and API decorators/annotations in source code to understand how code-level changes affect the public API contract.
- Changelog Generation: Automatically generate comprehensive API changelogs to keep documentation up-to-date and inform stakeholders of recent API modifications.
| name | openapi-diff |
|---|---|
| description | "Analyze OpenAPI/Swagger spec or source code changes. Triggers: API diff, spec changes, breaking changes, changelog" |
| version | 1.0.0 |
OpenAPI Diff Skill
Modes
- Spec File: Compare swagger.json/openapi.yaml versions
- Source Code: Analyze git diff for API decorators/annotations
Spec Structure
# OpenAPI 3.x: paths → components/schemas
# Swagger 2.x: paths → definitions
Change Detection
| Type | Look For |
|---|---|
| Endpoints | Routes, HTTP methods, paths, req/res types |
| Schemas | Fields, types, required/optional, validations |
| Parameters | Query, path, header, body params |
| Deprecation | @deprecated, deprecated flags |
Breaking Changes (Auto-flag)
- Endpoint removal
- Required param/field addition
- Response field removal
- Type change
- Enum value removal
- URL path change
Algorithm
Spec: Parse JSON/YAML → Compare paths/schemas → Classify → Detect breaking Source: git diff → Analyze decorators → Classify → Detect breaking
Language
Korean chars in code/spec → Korean output | Otherwise → English