菜单
Generate OpenAPI specs from code, validate API contracts, and check for breaking changes between versions.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Scan project, then generate or reconcile .primeignore patterns for smarter /prime loading
Run WCAG accessibility audits on frontend projects. Checks HTML semantics, ARIA usage, color contrast, and keyboard navigation patterns.
Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.
Incrementally fix TypeScript and build errors one at a time with verification. Invokes the build-error-resolver agent.
Create or verify a checkpoint in your workflow
ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads.
| name | api-contract |
| description | Generate OpenAPI specs from code, validate API contracts, and check for breaking changes between versions. |
| argument-hint | [--generate|--validate|--breaking|--endpoints] |
Generate OpenAPI specifications from code, validate API responses against contracts, and detect breaking changes.
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 |
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--endpoints)Scan the current project for all API endpoints:
FastAPI:
# 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:
# 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:
# 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)
--generate)FastAPI projects (auto-generated): FastAPI auto-generates OpenAPI at runtime. Extract it:
# 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:
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.
--validate)If an OpenAPI spec exists, validate the live API against it:
# Check if the spec exists
test -f openapi.json -o -f openapi.yaml
# For each endpoint in the spec, make a test request and verify:
# 1. Status code matches expected
# 2. Response content-type matches
# 3. Required fields are present
For FastAPI, the built-in /docs endpoint validates interactively. Suggest:
FastAPI projects self-validate via /docs (Swagger UI) and /redoc.
For automated validation:
pip install schemathesis
schemathesis run http://localhost:8000/openapi.json
--breaking)Compare current API surface with the last tagged version:
# Get the last tag
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
# Check out the old version's routes to a temp comparison
git show $LAST_TAG:path/to/routes.py 2>/dev/null > /tmp/old_routes.py
# Compare endpoint lists
# Current endpoints
grep -rn "@router\." --include="*.py" <path> | sed 's/.*@router\.//' > /tmp/current_endpoints.txt
# Old endpoints (from tag)
git show $LAST_TAG -- $(git ls-files '*.py' | grep -E 'route|router|api') 2>/dev/null | grep "@router\." | sed 's/.*@router\.//' > /tmp/old_endpoints.txt
# Diff
diff /tmp/old_endpoints.txt /tmp/current_endpoints.txt
Classify changes:
Output:
## Breaking Change Analysis: v1.2.1 -> current
### Breaking Changes (0)
None detected.
### Non-Breaking Changes (3)
- ADDED: GET /api/reports/shipping
- ADDED: POST /api/verification/complete
- ADDED: GET /api/schedule/import
### Potentially Breaking (1)
- MODIFIED: POST /api/orders — new required field `shipping_method`
Safe to deploy: YES/NO
--diff)Show API surface changes since last commit:
# Files that define routes
ROUTE_FILES=$(git diff --name-only HEAD~1 | grep -E "route|router|api|endpoint" | head -20)
# For each changed file, show the route changes
for f in $ROUTE_FILES; do
echo "=== $f ==="
git diff HEAD~1 -- "$f" | grep -E "^\+.*@(router|app)\.(get|post|put|delete)|^\-.*@(router|app)\.(get|post|put|delete)"
done
## API Contract Report: <project-name>
Endpoints: X total (Y GET, Z POST, W PUT, V DELETE)
OpenAPI spec: [exists/missing]
Last breaking change: [tag/date]
Contract health: [VALID/NEEDS_UPDATE/NO_SPEC]
schemathesis (Python) or dredd (Node)--generate writes an openapi.yaml skeleton only