api-contract

Files (2)

• README.md
• SKILL.md

SKILL.md (first lines)

# API Contract Manager

Generate OpenAPI specifications from code, validate API responses against contracts, and detect breaking changes.

## Supported Frameworks

Auto-detects the API framework in the current project:

| Framework | API Style | Route Discovery |
|-----------|-----------|-----------------|
| FastAPI | REST | Auto-generated OpenAPI at `/docs` and `/openapi.json` |
| Flask | REST | Blueprint / app route decorators |
| Express | REST | Manual router/app route definitions |

## Arguments

Parse `$ARGUMENTS`:

- **`--endpoints`:** List all API endpoints in the current project (default)
- **`--generate`:** Generate or update an OpenAPI spec from code
- **`--validate`:** Validate API responses against the spec
- **`--breaking`:** Check for breaking changes between current code and last tagged version
- **`--diff`:** Show API changes since last commit/tag

## Process

### Mode 1: Endpoint Discovery (`--endpoints`)

Scan the current project for all API endpoints:

**FastAPI:**
```bash
# Find all router files
grep -rn "@router\.\(get\|post\|put\|delete\|patch\)" --include="*.py" <path> | sed 's/.*@router\.//' | sed 's/(.*//' | sort
# Also check app-level routes
grep -rn "@app\.\(get\|post\|put\|delete\|patch\)" --include="*.py" <path> | head -20
# Find router registrations
grep -rn "include_router\|add_api_route" --include="*.py" <path> | head -20
```

**Flask:**
```bash
# Blueprint routes
grep -rn "@.*\.route\|@.*\.add_url_rule" --include="*.py" <path> | head -30
# Also check app-level
grep -rn "@app\.route" --include="*.py" <path> | head -20
```

**Express:**
```bash
# Router definitions
grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" --include="*.ts" --include="*.js" <path> | grep -v node_modules | head -30
```

Output:
```
## API Endpoints: <project-name>

| Method | Path | Handler | File |
|--------|------|---------|------|
| GET | /health | health_check | api/routers/health.py:12 |
| GET | /api/orders | list_orders | api/routers/orders.py:28 |
| POST | /api/orders | create_order | api/routers/orders.py:45 |
| GET | /api/orders/{id} | get_order | api/routers/orders.py:62 |
...

Total: X endpoints (Y GET, Z POST, W PUT, V DELETE)
```

### Mode 2: OpenAPI Spec Generation (`--generate`)

**FastAPI projects** (auto-generated):
FastAPI auto-generates OpenAPI at runtime. Extract it:
```bash
# If the app is running locally
curl -s http://localhost:8000/openapi.json 2>/dev/null | python3 -m json.tool > openapi.json

# If not running, check for existing spec
test -f <path>/openapi.json && echo "Spec exists" || echo "No spec file"
```

**Flask/Express projects** (manual generation):
Scan route definitions and generate a spec skeleton:

1. Collect all endpoints from Mode 1
2. For each endpoint, check for:
   - Request body schemas (Pydantic models, Zod schemas, JSON validation)
   - Response types (return type hints, response models)
   - Path parameters
   - Query parameters
   - Authentication requirements (decorators, middleware)
3. Generate an OpenAPI 3.0 YAML skeleton:

```yaml
openapi: "3.0.3"
info:
  title: <project-name> API
  version: <from-manifest>
paths:
  /health:
    get:
      summary: Health check
      responses:
        "200":
          description: Service healthy
  /api/orders:
    get:
      summary: List orders
      parameters: []
      responses:
        "200":
          description: Order list
```

Write to `openapi.yaml` in the project root.

### Mode 3: Contract Validation (`--validate`)

If an OpenAPI spec exists, validate the live API against it:

From PatriotAgenticLLC/better_claude_skillz, MIT.

More from PatriotAgenticLLC/better_claude_skillz