lmiranda
2d51df7a42
Phase 1b: Rename all ~94 commands across 12 plugins to /<noun> <action> sub-command pattern. Git-flow consolidated from 8→5 commands (commit variants absorbed into --push/--merge/--sync flags). Dispatch files, name: frontmatter, and cross-reference updates for all plugins. Phase 2: Design documents for 8 new plugins in docs/designs/. Phase 3: Scaffold 8 new plugins — saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot, data-seed, ops-release-manager, ops-deploy-pipeline, debug-mcp. Each with plugin.json, commands, agents, skills, README, and claude-md-integration. Marketplace grows from 12→20. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
124 lines
3.6 KiB
Markdown
124 lines
3.6 KiB
Markdown
---
|
|
name: api scaffold
|
|
description: Generate API routes, models, and schemas
|
|
agent: api-architect
|
|
---
|
|
|
|
# /api scaffold - Route and Model Scaffolding
|
|
|
|
## Skills to Load
|
|
|
|
- skills/framework-detection.md
|
|
- skills/route-patterns.md
|
|
- skills/openapi-conventions.md
|
|
- skills/visual-header.md
|
|
|
|
## Visual Output
|
|
|
|
Display header: `API-PLATFORM - Scaffold`
|
|
|
|
## Usage
|
|
|
|
```
|
|
/api scaffold <resource-name> [--methods=GET,POST,PUT,DELETE] [--nested-under=<parent>]
|
|
```
|
|
|
|
**Arguments:**
|
|
- `<resource-name>`: Name of the resource (e.g., `users`, `orders`, `products`)
|
|
- `--methods`: Comma-separated HTTP methods (default: all CRUD)
|
|
- `--nested-under`: Create as nested resource under parent (e.g., `--nested-under=users`)
|
|
|
|
## Prerequisites
|
|
|
|
Run `/api setup` first. This command reads `.api-platform.json` for framework and conventions.
|
|
|
|
## Process
|
|
|
|
### 1. Read Configuration
|
|
|
|
Load `.api-platform.json` to determine:
|
|
- Target framework (FastAPI or Express)
|
|
- Route and model directories
|
|
- Versioning scheme
|
|
- Response format conventions
|
|
|
|
### 2. Generate Route File
|
|
|
|
Create route/controller file with endpoints:
|
|
|
|
**FastAPI Example (`routes/{resource}.py`):**
|
|
- `GET /{version}/{resource}` - List with pagination, filtering, sorting
|
|
- `GET /{version}/{resource}/{id}` - Get by ID with 404 handling
|
|
- `POST /{version}/{resource}` - Create with request body validation
|
|
- `PUT /{version}/{resource}/{id}` - Full update with 404 handling
|
|
- `PATCH /{version}/{resource}/{id}` - Partial update
|
|
- `DELETE /{version}/{resource}/{id}` - Delete with 204 response
|
|
|
|
**Express Example (`routes/{resource}.js`):**
|
|
- Same endpoints adapted to Express router patterns
|
|
- Includes error handling middleware chain
|
|
|
|
### 3. Generate Request/Response Models
|
|
|
|
Create schema definitions appropriate to the framework:
|
|
|
|
- **FastAPI**: Pydantic models in `models/{resource}.py`
|
|
- `{Resource}Create` - POST/PUT request body
|
|
- `{Resource}Update` - PATCH request body (all fields optional)
|
|
- `{Resource}Response` - Response model with `id`, timestamps
|
|
- `{Resource}List` - Paginated list wrapper
|
|
|
|
- **Express**: JSON Schema or Zod schemas in `schemas/{resource}.js`
|
|
- Create schema, Update schema, Response schema
|
|
|
|
### 4. Generate Validation Schemas
|
|
|
|
Add input validation:
|
|
- Required fields, type constraints, string length limits
|
|
- Enum values where appropriate
|
|
- Nested object validation for complex resources
|
|
|
|
### 5. Register Routes
|
|
|
|
Update the main router/app file to include new routes:
|
|
- Add import statement
|
|
- Register route prefix
|
|
- Maintain alphabetical ordering of imports
|
|
|
|
## Output Format
|
|
|
|
```
|
|
+----------------------------------------------------------------------+
|
|
| API-PLATFORM - Scaffold |
|
|
+----------------------------------------------------------------------+
|
|
|
|
Resource: orders
|
|
Framework: FastAPI
|
|
Versioning: /v1/
|
|
|
|
Files Created:
|
|
[+] app/routes/orders.py (6 endpoints)
|
|
[+] app/models/orders.py (4 Pydantic models)
|
|
[~] app/main.py (route registered)
|
|
|
|
Endpoints Generated:
|
|
GET /v1/orders List with pagination
|
|
GET /v1/orders/{id} Get by ID
|
|
POST /v1/orders Create
|
|
PUT /v1/orders/{id} Full update
|
|
PATCH /v1/orders/{id} Partial update
|
|
DELETE /v1/orders/{id} Delete
|
|
|
|
Next Steps:
|
|
- Add business logic to route handlers
|
|
- Run /api validate to check against OpenAPI spec
|
|
- Run /api test-routes to generate test cases
|
|
```
|
|
|
|
## Nested Resources
|
|
|
|
When `--nested-under` is specified:
|
|
- Routes are prefixed: `/{parent}/{parent_id}/{resource}`
|
|
- Models include `{parent}_id` foreign key field
|
|
- Route file includes parent ID path parameter validation
|