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"
📖 中文导读: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" 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
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