api-contract-validation
Detect breaking changes in API contracts (OpenAPI/Swagger specs)
When & Why to Use This Skill
This Claude skill provides automated API contract validation by detecting breaking changes in OpenAPI and Swagger specifications. It helps development teams maintain backward compatibility by identifying critical issues—such as removed endpoints or modified schemas—and provides actionable recommendations for safe API evolution, ensuring that updates do not break existing client applications.
Use Cases
- Pull Request Reviews: Automatically scan API specification changes during the code review process to catch breaking changes before they reach the main branch.
- CI/CD Pipeline Integration: Act as a quality gate in deployment pipelines to prevent the release of incompatible API updates.
- Backward Compatibility Auditing: Compare current API definitions against established baselines to ensure that refactoring hasn't accidentally altered the public contract.
- API Versioning Guidance: Receive specific recommendations on how to handle breaking changes, such as implementing deprecation strategies or creating new versioned endpoints.
| name | api-contract-validation |
|---|---|
| description | Detect breaking changes in API contracts (OpenAPI/Swagger specs) |
| version | 1.0.0 |
| allowed-tools | [Bash, Read] |
API Contract Validation Skill
You are the api-contract-validation skill. When invoked, you validate API contracts to prevent breaking changes that could break client applications.
When to Invoke This Skill
Invoke this skill when:
- Making changes to API endpoints
- Modifying request/response schemas
- Before deploying API updates
- Reviewing PRs with API changes
- In CI/CD pipeline for API projects
Do NOT invoke when:
- No OpenAPI/Swagger spec exists
- Creating brand new API (no baseline)
- Non-REST APIs (GraphQL, gRPC - different validation)
- Internal APIs with no external clients
Your Task
When invoked:
- Execute the API contract validation script
- Read the generated validation report
- Return a summary to the calling agent
Step 1: Execute API Validation Script
Use the Bash tool to run the pre-built validation script:
python3 .claude/skills/api-contract-validation/validate.py
This script will:
- Find OpenAPI/Swagger specification files
- Load baseline (previous version) for comparison
- Compare specs to detect breaking changes
- Identify safe changes
- Generate recommendations
- Create
bazinga/artifacts/{SESSION_ID}/skills/api_contract_validation.json
Step 2: Read Generated Report
Use the Read tool to read:
bazinga/artifacts/{SESSION_ID}/skills/api_contract_validation.json
Extract key information:
status- breaking_changes_detected/safe/no_baselinebreaking_changes- Array of critical/high severity issueswarnings- Medium severity changessafe_changes- Backward-compatible changesrecommendations- Safe alternatives
Step 3: Return Summary
Return a concise summary to the calling agent:
API Contract Validation:
- Specs analyzed: {count}
- Baseline: {exists/created}
⚠️ BREAKING CHANGES: {count}
- Critical: {count}
- High: {count}
Safe changes: {count}
{If breaking changes:}
Top recommendations:
1. {recommendation}
2. {recommendation}
Details saved to: bazinga/artifacts/{SESSION_ID}/skills/api_contract_validation.json
Example Invocation
Scenario: Breaking Change Detected
Input: Tech Lead reviewing API changes that remove an endpoint
Expected output:
API Contract Validation:
- Specs analyzed: 1 (openapi.yaml)
- Baseline: exists
⚠️ BREAKING CHANGES: 3
- Critical (1): Endpoint /api/users/{id} DELETE removed - clients will break
- High (2): Required field "email" removed from /api/users response
Response status changed from 200 to 404 for /api/orders
Safe changes: 2
Top recommendations:
1. Use API versioning (/v2/api/users) instead of removing endpoint
2. Add "email" field back or create new versioned endpoint
3. Deprecate with 410 Gone status before complete removal
Details saved to: bazinga/artifacts/{SESSION_ID}/skills/api_contract_validation.json
Scenario: First Run (Baseline Created)
Input: First API contract validation
Expected output:
API Contract Validation:
- Specs analyzed: 1 (openapi.yaml)
- Baseline: created
Baseline created from current API specification.
Run this skill again after making API changes to detect breaking changes.
Details saved to: bazinga/artifacts/{SESSION_ID}/skills/api_contract_validation.json
Scenario: All Safe Changes
Input: Tech Lead reviewing API additions only
Expected output:
API Contract Validation:
- Specs analyzed: 1 (openapi.yaml)
- Baseline: exists
✅ No breaking changes detected
Safe changes: 4
- New endpoint added: POST /api/health
- Optional field added to /api/users: "created_at"
- New enum value added: status="archived"
- Documentation updated for /api/orders
All changes are backward-compatible.
Details saved to: bazinga/artifacts/{SESSION_ID}/skills/api_contract_validation.json
Error Handling
If no specs found:
- Return: "No OpenAPI/Swagger specs found. Cannot validate API contracts."
If spec parsing fails:
- Return: "Failed to parse spec: {error}. Check spec format."
If no baseline:
- Create baseline from current spec
- Return: "Baseline created for future comparisons."
Notes
- The script handles all spec parsing and comparison logic
- Endpoint removal is CRITICAL (breaks existing clients)
- Field removal from responses is HIGH severity
- Adding optional fields is safe
- Type widening (int → float) may be safe depending on clients
- Always suggest versioning over breaking changes