API Contract Enforcement Skill

Ensures REST API implementations strictly match OpenAPI 3.x specifications for routes, methods, payloads, and responses.

Quick Start

Validate API implementation against spec:

bash

python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py <openapi-spec.yaml> <backend-module>

Example:

bash

python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main

When to Use This Skill

Trigger this skill when:

•Implementing new REST endpoints (validate against spec before PR)
•Reviewing API changes or pull requests
•Before deploying to production (contract compliance gate)
•Debugging API integration failures (check for mismatches)
•Refactoring API endpoints (ensure contract unchanged)
•Updating OpenAPI spec (verify all endpoints match)

Validation Process

Step 1: Locate Artifacts

Ensure you have:

•OpenAPI spec: openapi.yaml or openapi.json
•Backend module: Python module containing the API app (e.g., myapp.main)

Common locations:

•OpenAPI spec: api/openapi.yaml, docs/openapi.yaml, or root
•Backend module: main.py, app/main.py, or similar entry point

Step 2: Run Validation

Execute the validation script:

bash

python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py <openapi-spec> <backend-module>

The script performs these validations:

•Route/method/path validation: Each OpenAPI path+method exists in implementation
•Request payload validation: Request body fields, types, and required constraints match
•Response payload validation: Response structure, types, and status codes match
•Parameter validation: Query/path/header parameters are correctly implemented

Step 3: Review Results

Validation outputs:

code

PASS/FAIL: <overall status>
✓ GET /api/users - routes match
✗ POST /api/users - request body missing field 'email'
✓ GET /api/users/{id} - responses match

Contract Violations:
[Details of each mismatch]

Recommendations:
[Actionable fixes]

Step 4: Fix Contract Violations

For each violation:

Missing endpoint: Implement the missing route/method in your backend

python

@app.post("/api/users")  # Missing in implementation
def create_user(user: UserCreate):
    return user

Request body mismatch: Update implementation to match spec

python

# Spec requires: email (required), name (optional)
class UserCreate(BaseModel):
    email: str  # This was missing
    name: Optional[str]

Response mismatch: Fix response structure or update spec

python

# Spec expects {id, email, name}, implementation returns {id, email}
def get_user(user_id: int):
    return {"id": user_id, "email": "...", "name": "..."}  # Added 'name'

Parameter mismatch: Add or correct parameters in route definition

python

@app.get("/api/users/{id}")  # Spec has required path parameter 'id'
def get_user(id: int):
    ...

Step 5: Revalidate

Run validation again after fixes until all checks pass.

Validation Rules

Route/Method/Path Validation

Checks that every endpoint defined in OpenAPI spec is implemented:

•HTTP methods match (GET, POST, PUT, DELETE, etc.)
•URL paths match exactly (including parameters like {id})
•Path parameters are properly declared in function signatures

Example violation:

•Spec: GET /api/users/{id}
•Impl: GET /api/users/{user_id}
•Issue: Path parameter name mismatch

Request Payload Validation

Compares request body schemas with implementation:

•All required fields present in request model
•Field types match (string, integer, boolean, array, object)
•Nested structures correctly defined
•Validation rules (min/max length, patterns) considered warnings

Example violation:

•Spec requires: email: string (required)
•Impl: email: string (optional)
•Issue: Required field not enforced in implementation

Response Payload Validation

Verifies response structure matches OpenAPI definitions:

•Response status codes documented
•Response body structure matches schema
•Field types consistent
•Nested objects correctly structured

Example violation:

•Spec returns: {id, email, name, created_at}
•Impl returns: {id, email}
•Issue: Missing fields in response

Parameter Validation

Ensures query, path, and header parameters are correct:

•Required parameters present
•Optional parameters have defaults or nullable types
•Parameter types match

Example violation:

•Spec: GET /api/items?limit=10&offset=0
•Impl: GET /api/items
•Issue: Query parameters not implemented

Common Issues and Solutions

Missing Endpoint

Error: Endpoint GET /api/missing not found in implementation Fix: Implement the endpoint or remove from spec

Path Parameter Mismatch

Error: Path parameter 'id' in spec vs 'user_id' in implementation Fix: Rename parameter to match spec or update spec

Required Field Missing

Error: Request body missing required field 'email' Fix: Add field to request model with required type

Response Structure Mismatch

Error: Response missing field 'created_at' Fix: Add field to response or update spec if field not needed

Status Code Not Documented

Error: Endpoint returns 401 but not in OpenAPI spec Fix: Add response for 401 status code in spec or fix auth

Integration with Development Workflow

Before PR Submission

bash

# Run validation in CI/CD
python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main
# Exit code 0 on success, 1 on contract violation

During Implementation

bash

# Validate frequently to catch issues early
python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main

After Spec Updates

bash

# When OpenAPI spec changes, verify all endpoints still match
python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main

Advanced Usage

Specific Endpoints Only

Validate specific endpoint groups:

python

# Modify script to filter by path prefix
python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main --path-prefix "/api/v2"

Strict Mode

Fail on warnings (e.g., validation rules not implemented):

bash

python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main --strict

Output Format

Generate JSON for CI/CD integration:

bash

python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main --format json

Reference Materials

•OPENAPI_BEST_PRACTICES.md: Guidelines for writing clear OpenAPI specs
•FASTAPI_CONTRACT_PATTERNS.md: Common patterns for contract-compliant FastAPI endpoints
•VALIDATION_RULES.md: Detailed explanation of all validation rules

Framework Support

Currently supports:

•FastAPI: Automatic schema extraction from Pydantic models
•Flask: Manual route inspection (limited automatic validation)

For other frameworks, see VALIDATION_RULES.md for manual validation guidance.