ISA-Frontend/.claude/skills/api-change-analyzer/SKILL.md

name, description

name	description
api-change-analyzer	This skill should be used when analyzing Swagger/OpenAPI specification changes BEFORE regenerating API clients. It compares old vs new specs, categorizes changes as breaking/compatible/warnings, finds affected code, and generates migration strategies. Use this skill when the user wants to check API changes safely before sync, mentions "check breaking changes", or needs impact assessment.

API Change Analyzer

Overview

Analyze Swagger/OpenAPI specification changes to detect breaking changes before regeneration. Provides detailed comparison, impact analysis, and migration recommendations.

When to Use This Skill

Invoke when user wants to:

• Check API changes before regeneration
• Assess impact of backend updates
• Plan migration for breaking changes
• Mentioned "breaking changes" or "API diff"

Analysis Workflow

Step 1: Backup and Generate Temporarily

cp -r generated/swagger/[api-name] /tmp/[api-name].backup
npm run generate:swagger:[api-name]

Step 2: Compare Files

diff -u /tmp/[api-name].backup/models.ts generated/swagger/[api-name]/models.ts
diff -u /tmp/[api-name].backup/services.ts generated/swagger/[api-name]/services.ts

Step 3: Categorize Changes

🔴 Breaking (Critical):

• Removed properties from response models
• Changed property types (string → number)
• Removed endpoints
• Optional → required fields
• Removed enum values

✅ Compatible (Safe):

• Added properties (non-breaking)
• New endpoints
• Added optional parameters
• New enum values

⚠️ Warnings (Review):

• Property renamed (old removed + new added)
• Changed default values
• Changed validation rules
• Added required request fields

Step 4: Analyze Impact

For each breaking change, use Explore agent to find usages:

# Example: Find usages of removed property
grep -r "removedProperty" libs/*/data-access --include="*.ts"

List:

• Affected files
• Services impacted
• Estimated refactoring effort

Step 5: Generate Migration Strategy

Based on severity:

High Impact (multiple breaking changes):

1. Create migration branch
2. Document all changes
3. Update services incrementally
4. Comprehensive testing

Medium Impact:

1. Fix compilation errors
2. Update affected tests
3. Deploy with monitoring

Low Impact:

1. Minor updates
2. Deploy

Step 6: Create Report

API Breaking Changes Analysis
==============================

API: [api-name]
Analysis Date: [timestamp]

📊 Summary
----------
Breaking Changes: XX
Warnings: XX
Compatible Changes: XX

🔴 Breaking Changes
-------------------
1. Removed Property: OrderResponse.deliveryDate
   Files Affected: 2
   - libs/oms/data-access/src/lib/services/order.service.ts:45
   - libs/oms/feature/order-detail/src/lib/component.ts:78
   Impact: Medium
   Fix: Remove references or use alternativeDate

2. Type Changed: ProductResponse.price (string → number)
   Files Affected: 1
   - libs/catalogue/data-access/src/lib/services/product.service.ts:32
   Impact: High
   Fix: Update parsing logic

⚠️ Warnings
-----------
1. Possible Rename: CustomerResponse.customerName → fullName
   Action: Verify with backend team

✅ Compatible Changes
---------------------
1. Added Property: OrderResponse.estimatedDelivery
2. New Endpoint: GET /api/v2/orders/bulk

💡 Migration Strategy
---------------------
Approach: [High/Medium/Low Impact]
Estimated Effort: [hours]
Steps: [numbered list]

🎯 Recommendation
-----------------
[Proceed with sync / Fix critical issues first / Coordinate with backend]

Step 7: Cleanup

rm -rf /tmp/[api-name].backup
# Or restore if needed

References

• CLAUDE.md API Integration
• Semantic Versioning: https://semver.org