Validates REST API implementations against OpenAPI 3.x specifications. Use when (1) Implementing or reviewing API endpoints, (2) Before deploying API changes to production, (3) Ensuring contract compliance between spec and implementation, or (4) Debugging API integration issues caused by contract mismatches. Works with Python (FastAPI/Flask) backends.
Ensures REST API implementations strictly match OpenAPI 3.x specifications for routes, methods, payloads, and responses.
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
Trigger this skill when:
Ensure you have:
openapi.yaml or openapi.jsonmyapp.main)Common locations:
api/openapi.yaml, docs/openapi.yaml, or rootmain.py, app/main.py, or similar entry pointExecute the validation script:
python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py <openapi-spec> <backend-module>
The script performs these validations:
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]
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):
...
Run validation again after fixes until all checks pass.
Checks that every endpoint defined in OpenAPI spec is implemented:
{id})Example violation:
GET /api/users/{id}GET /api/users/{user_id}Compares request body schemas with implementation:
Example violation:
email: string (required)email: string (optional)Verifies response structure matches OpenAPI definitions:
Example violation:
{id, email, name, created_at}{id, email}Ensures query, path, and header parameters are correct:
Example violation:
GET /api/items?limit=10&offset=0GET /api/itemsError: Endpoint GET /api/missing not found in implementation
Fix: Implement the endpoint or remove from spec
Error: Path parameter 'id' in spec vs 'user_id' in implementation
Fix: Rename parameter to match spec or update spec
Error: Request body missing required field 'email'
Fix: Add field to request model with required type
Error: Response missing field 'created_at'
Fix: Add field to response or update spec if field not needed
Error: Endpoint returns 401 but not in OpenAPI spec
Fix: Add response for 401 status code in spec or fix auth
# 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
# Validate frequently to catch issues early
python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main
# When OpenAPI spec changes, verify all endpoints still match
python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main
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"
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
Generate JSON for CI/CD integration:
python .claude/skills/api-contract-enforcement/scripts/validate_api_contract.py openapi.yaml myapp.main --format json
Currently supports:
For other frameworks, see VALIDATION_RULES.md for manual validation guidance.