API Contract Validator

Purpose

Validates API contracts for correctness, compatibility, and compliance. Tests REST APIs against OpenAPI/Swagger specifications. Detects breaking changes between versions and validates runtime responses against schemas.

Triggers

Use this skill when:

• "validate API contract"
• "test API endpoints"
• "check for breaking changes"
• "API compatibility test"
• "contract testing"
• "verify OpenAPI spec"

When to Use

• New API version deployment
• Consumer complaints about changes
• Pre-release validation
• Multi-service integration testing
• Third-party API consumption validation

When NOT to Use

• Unit testing internal functions (use unit-test-generator)
• Load testing (use performance-benchmark)
• Security testing (use security-test-suite)
• Data quality validation (use data-validation)

Core Instructions

Validation Categories

Breaking Change Detection

Validation Procedure

1. Specification Analysis Phase

   • Load OpenAPI/Swagger specification
   • Validate spec structure and completeness
   • Identify all endpoints and schemas
   • Parse security definitions

2. Breaking Change Detection Phase

   • Compare current spec to previous version
   • Identify removed endpoints/methods
   • Detect schema changes (fields, types)
   • Flag new required parameters

3. Runtime Validation Phase (if enabled)

   • Make HTTP requests to live API
   • Validate response status codes
   • Check response against schema
   • Measure response times

Templates

Validation Report

# API Contract Validation Report

**Generated:** {timestamp}
**Specification:** {spec_path}

## Summary

| Metric | Value |
| ------ | ----- |
| Total Endpoints | {count} |
| Passed | {passed} |
| Failed | {failed} |
| Breaking Changes | {breaking_count} |

## Breaking Changes

### {endpoint_path}

**Type:** {change_type}
**Description:** {description}
**Migration:** {migration_guide}

## Endpoint Tests

| Method | Path | Status | Response Time |
| ------ | ---- | ------ | ------------- |
| {method} | {path} | {status_icon} | {time}ms |

Example

Input: Compare two OpenAPI specs for breaking changes

Output:

## Breaking Changes

### /api/users/{id}

**Type:** removed_field
**Description:** Field 'legacy_id' was removed from response
**Migration:** Update consumers to use 'id' field instead

### /api/orders

**Type:** added_required
**Description:** Parameter 'tenant_id' became required
**Migration:** All consumers must now provide tenant_id header

Validation Checklist

• OpenAPI specification is valid and complete
• All endpoints have documented responses
• Breaking changes have migration guidance
• Runtime tests cover all documented endpoints
• Error responses follow standard format
• Authentication methods are properly tested

Related Skills

• unit-test-generator - For internal function testing
• security-test-suite - For API security testing
• performance-benchmark - For API load testing