leo-claude-mktplace/plugins/saas-api-platform/commands/api-scaffold.md

name, description, agent

name	description	agent
api scaffold	Generate API routes, models, and schemas	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