ISA-Frontend/.claude/skills/swagger-sync-manager/SKILL.md

name, description

name	description
swagger-sync-manager	This skill should be used when regenerating Swagger/OpenAPI TypeScript API clients in the ISA-Frontend monorepo. It handles generation of all 10 API clients (or specific ones), Unicode cleanup, breaking change detection, TypeScript validation, and affected test execution. Use this skill when the user requests API sync, mentions "regenerate swagger", or indicates backend API changes.

Swagger Sync Manager

Overview

Automate the regeneration of TypeScript API clients from Swagger/OpenAPI specifications. Handles 10 API clients with automatic post-processing, breaking change detection, impact analysis, and validation.

When to Use This Skill

Invoke when user requests:

• API client regeneration
• "sync swagger" or "update API clients"
• Backend API changes need frontend updates

Available APIs

availability-api, cat-search-api, checkout-api, crm-api, eis-api, inventory-api, isa-api, oms-api, print-api, wws-api

Sync Workflow

Step 1: Pre-Generation Check

# Check uncommitted changes
git status generated/swagger/

If changes exist, warn user and ask to proceed.

Step 2: Backup Current State (Optional)

cp -r generated/swagger generated/swagger.backup.$(date +%s)

Step 3: Run Generation

# All APIs
npm run generate:swagger

# Specific API (if api-name provided)
npm run generate:swagger:[api-name]

Step 4: Verify Unicode Cleanup

Check tools/fix-files.js executed. Scan for remaining Unicode issues:

grep -r "\\\\u00" generated/swagger/ || echo "✅ No Unicode issues"

Step 5: Detect Breaking Changes

For each modified API:

git diff generated/swagger/[api-name]/

Identify:

• 🔴 Removed properties
• 🔴 Changed types
• 🔴 Removed endpoints
• ✅ Added properties (safe)
• ✅ New endpoints (safe)

Step 6: Impact Analysis

Use Explore agent to find affected files:

• Search for imports from @generated/swagger/[api-name]
• List data-access services using changed APIs
• Estimate refactoring scope

Step 7: Validate

# TypeScript compilation
npx tsc --noEmit

# Run affected tests
npx nx affected:test --skip-nx-cache

# Lint affected
npx nx affected:lint

Step 8: Generate Report

Swagger Sync Complete
=====================

APIs Regenerated: [all | specific]
Files Changed: XX
Breaking Changes: XX

🔴 Breaking Changes
-------------------
- [API]: [Property removed/type changed]
- Affected files: [list]

✅ Compatible Changes
---------------------
- [API]: [New properties/endpoints]

📊 Validation
-------------
TypeScript: ✅/❌
Tests: XX/XX passing
Lint: ✅/❌

💡 Next Steps
-------------
[Fix breaking changes / Deploy]

Error Handling

Generation fails: Check OpenAPI spec URLs in package.json

Unicode cleanup fails: Run node tools/fix-files.js manually

TypeScript errors: Review breaking changes, update affected services

References

• CLAUDE.md API Integration section
• package.json swagger generation scripts