api-contract-validator

name	api-contract-validator
description	Validates API contracts for correctness, compatibility, and compliance. Tests REST APIs against OpenAPI/Swagger specifications. Detects breaking changes between versions, validates runtime responses against schemas, and ensures backward compatibility before deployment.
license	MIT
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep","WebFetch"]
compatibility	{"claude-code":">=1.0.0"}
metadata	{"version":"1.0.0","author":"QuantQuiver AI R&D","category":"testing","tags":["api-testing","openapi","contract-testing","breaking-changes"]}

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

Category	Description	Severity
Schema Compliance	Response matches OpenAPI schema	Critical
Status Codes	Correct codes for scenarios	Critical
Breaking Changes	Backward incompatible changes	Critical
Deprecations	Deprecated fields/endpoints	Warning
Headers	Required headers present	Medium
Error Format	Error responses follow standard	Low

Breaking Change Detection

Change Type	Severity	Example
Removed endpoint	Critical	DELETE /api/v1/users removed
Removed field	Critical	user.legacy_id no longer returned
Type change	Critical	id changed from string to integer
Added required param	Critical	New required tenant_id parameter
Changed authentication	Critical	API key to OAuth2
Removed enum value	High	Status no longer accepts "pending"

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