---
name: api-change-analyzer
description: 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

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

### Step 2: Compare Files

```bash
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:

```bash
# 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

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

## References

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