api-contract-sync_skill

Overview

This skill validates and syncs API specifications (OpenAPI/Swagger and GraphQL) with backend implementations, detects breaking changes, and generates type-safe TypeScript clients and hooks. It helps teams keep documentation, implementation, and frontend types aligned to reduce runtime errors and integration friction. Use it to automate validation, diff API versions, and produce migration guides and coverage reports.

How this skill works

The skill reads spec files (.yaml/.json/.graphql), parses schemas, and runs structured checks for syntax, references, and completeness. It cross-references extracted endpoints and types with the codebase to find undocumented or missing implementations and reports precise file locations. When comparing two spec versions it classifies changes as breaking or non-breaking and produces migration instructions. It can generate TypeScript interfaces, client functions, and optional React Query hooks from the parsed models.

When to use it

• Validating OpenAPI/Swagger (.yaml, .json) or GraphQL (.graphql, .gql) spec files
• Reviewing API changes in pull requests to detect breaking edits
• Generating TypeScript types and client functions for frontend teams
• Verifying that backend route/resolver implementations match documented contracts
• Creating migration guides and versioning strategies after spec changes

Best practices

• Keep schemas DRY: use $ref for shared models across the spec
• Version APIs explicitly (path prefix or headers) and follow semver for breaking changes
• Include request/response examples and document error responses
• Deprecate fields before removal and provide clear timelines in the spec
• Run spec validation and implementation matching as part of CI to catch drift early

Example use cases

• Run a CI job that validates openapi.yaml and fails builds on syntax or missing descriptions
• Compare api-v1.yaml and api-v2.yaml to produce a migration guide listing breaking changes
• Scan a repository to produce an API coverage report showing documented vs implemented endpoints
• Generate TypeScript interfaces and React Query hooks from OpenAPI to ensure type-safe frontend calls
• Audit GraphQL schema to ensure all fields have resolver implementations and no circular dependencies