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:

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

Example:

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:

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:

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

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

Request body mismatch: Update implementation to match spec

# 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

# 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

@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

# 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

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

After Spec Updates

# 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:

# 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):

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

Output Format

Generate JSON for CI/CD integration:

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.