API Contract Sync Manager

What this skill does

# API Contract Sync Manager

Maintain synchronization between API specifications and their implementations, detect breaking changes, and generate client code to ensure contracts stay reliable across frontend and backend teams.

## When to Use This Skill

Use this skill when:
- Working with OpenAPI/Swagger specification files (`.yaml`, `.json`)
- Managing GraphQL schemas (`.graphql`, `.gql`)
- Reviewing API changes in pull requests
- Generating TypeScript types or client code from specs
- Validating that implementations match documented APIs
- Detecting breaking vs. non-breaking API changes
- Creating API versioning strategies
- Onboarding new developers to an API-driven codebase

## Core Capabilities

### 1. Spec Validation

Validate API specification files for correctness and completeness:

**OpenAPI/Swagger Validation**:
- Check schema syntax and structure
- Validate against OpenAPI 3.0/3.1 standards
- Ensure all endpoints have proper descriptions
- Verify request/response schemas are complete
- Check for required security definitions
- Validate parameter types and constraints

**GraphQL Validation**:
- Parse and validate SDL (Schema Definition Language)
- Check for schema stitching issues
- Validate resolver coverage
- Detect circular dependencies
- Verify input/output type consistency

**Validation Approach**:
1. Read the spec file using the Read tool
2. Parse the structure (YAML/JSON for OpenAPI, SDL for GraphQL)
3. Check for common issues:
   - Missing required fields
   - Invalid references (`$ref`)
   - Inconsistent naming conventions
   - Missing examples or descriptions
   - Security scheme gaps
4. Report findings with line numbers and suggestions

### 2. Implementation Matching

Cross-reference API specifications with actual code implementations:

**For REST APIs**:
1. Extract all endpoints from OpenAPI spec (paths, methods)
2. Search codebase for route definitions:
   - Express.js: `app.get()`, `router.post()`, etc.
   - FastAPI: `@app.get()`, `@router.post()`
   - Django: `path()`, `urlpatterns`
   - Spring Boot: `@GetMapping`, `@PostMapping`
3. Compare spec endpoints against implemented routes
4. Flag discrepancies:
   - Documented but not implemented
   - Implemented but not documented
   - Parameter mismatches
   - Response type differences

**For GraphQL**:
1. Extract types, queries, mutations from schema
2. Search for resolver implementations
3. Verify all schema fields have resolvers
4. Check resolver signatures match schema types

**Implementation Matching Steps**:
```
1. Parse spec → extract endpoints/operations
2. Use Grep to find route handlers in codebase
3. Compare and categorize:
   - ✓ Matched: spec and implementation align
   - ⚠ Drift: partial match with differences
   - ✗ Missing: documented but not implemented
   - ⚠ Undocumented: implemented but not in spec
4. Generate coverage report
```

### 3. Breaking Change Detection

Compare two versions of an API spec to detect breaking vs. non-breaking changes:

**Breaking Changes** (require version bump):
- Removed endpoints or operations
- Removed required request parameters
- Changed parameter types (e.g., string → number)
- Made optional parameters required
- Removed response properties that clients depend on
- Changed response status codes
- Renamed endpoints, parameters, or fields
- Stricter validation rules (e.g., regex patterns)

**Non-Breaking Changes** (safe to deploy):
- Added new endpoints
- Added optional parameters
- Made required parameters optional
- Added new response properties
- Expanded enum values
- Improved descriptions/examples
- Added deprecation warnings

**Change Detection Process**:
1. Read both spec versions (old and new)
2. Compare schemas field by field
3. Categorize each change as breaking or non-breaking
4. Generate migration guide with:
   - Summary of breaking changes
   - Impact on existing clients
   - Required client updates
   - Recommended versioning strategy

### 4. Client Code Generation

Generate type-safe client code from API specifications:

**TypeScript Interfaces**:
```typescript
// From OpenAPI schema
interface User {
  id: string;
  email: string;
  name?: string;
  createdAt: Date;
}

interface CreateUserRequest {
  email: string;
  name?: string;
}

interface CreateUserResponse {
  user: User;
  token: string;
}
```

**API Client Functions**:
```typescript
// HTTP client with proper typing
async function createUser(
  data: CreateUserRequest
): Promise<CreateUserResponse> {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });
  return response.json();
}
```

**React Query Hooks**:
```typescript
// Auto-generated hooks for data fetching
function useUser(userId: string) {
  return useQuery(['user', userId], () => 
    fetch(`/api/users/${userId}`).then(r => r.json())
  );
}

function useCreateUser() {
  return useMutation((data: CreateUserRequest) =>
    fetch('/api/users', {
      method: 'POST',
      body: JSON.stringify(data)
    }).then(r => r.json())
  );
}
```

**Generation Steps**:
1. Parse OpenAPI/GraphQL schema
2. Extract all data models (schemas, types)
3. Generate TypeScript interfaces with proper types
4. Create client functions for each endpoint
5. Optionally generate hooks for React Query/SWR
6. Add JSDoc comments from spec descriptions

### 5. Coverage Analysis

Identify gaps between documentation and implementation:

**Analysis Report Structure**:
```
API Coverage Report
==================

Documented Endpoints: 45
Implemented Endpoints: 42
Coverage: 93%

Missing Implementations:
- DELETE /api/users/{id} (documented but not found)
- POST /api/users/{id}/suspend (documented but not found)

Undocumented Endpoints:
- GET /api/internal/health (found in code, not in spec)
- POST /api/debug/reset (found in code, not in spec)

Mismatched Signatures:
- POST /api/users
  Spec expects: { email, name, role }
  Code accepts: { email, name } (missing 'role')
```

**Coverage Analysis Process**:
1. Run implementation matching (see section 2)
2. Calculate coverage percentage
3. List all discrepancies with file locations
4. Prioritize issues by severity
5. Suggest next steps to achieve 100% coverage

### 6. Migration Guides

Create upgrade guides when API versions change:

**Migration Guide Template**:
```markdown
# API v2.0 Migration Guide

## Breaking Changes

### 1. User Creation Endpoint
**Change**: Required `role` field added to POST /api/users
**Impact**: All user creation calls will fail without this field
**Action Required**:
- Update all POST /api/users calls to include `role`
- Default to 'member' if no specific role needed

Before:
```json
{ "email": "[email protected]", "name": "John" }
```

After:
```json
{ "email": "[email protected]", "name": "John", "role": "member" }
```

### 2. Authentication Token Format
**Change**: JWT tokens now use RS256 instead of HS256
**Impact**: Token validation must be updated
**Action Required**:
- Update JWT verification libraries
- Fetch new public key from /.well-known/jwks.json
```

**Guide Generation Steps**:
1. Detect all breaking changes (see section 3)
2. Group changes by endpoint or feature
3. For each change, document:
   - What changed and why
   - Impact on existing clients
   - Required code updates with before/after examples
   - Timeline for deprecation
4. Add general upgrade instructions

## Best Practices

### For OpenAPI Specs
1. **Use $ref liberally**: Define schemas once, reference everywhere
2. **Version your APIs**: Use `/v1/`, `/v2/` prefixes or version headers
3. **Add examples**: Include request/response examples in spec
4. **Document errors**: Define all possible error responses
5. **Security first**: Always specify security requirements

### For GraphQL Schemas
1. **Use descriptions**: Document all types, fields, and arguments
2. **Deprecate, don't remove**: Use `@deprecated` directive
3. **Input validation**: Use custom scalars for validated types
4. **Pag