api-generator

What this skill does

# Frontend API Generator

## Core Principles

1. **Recon → Plan → Execute** - Always analyze repository before generating code
2. **Incremental changes only** - Never destructive refactors
3. **Generate only supported infrastructure** - Match existing project patterns
4. **Ask when uncertain** - Use Interview Mode for ambiguity
5. **User must approve plan** - No execution without confirmation

## Phase 1: Project Recon (MANDATORY)

Before generating any code, analyze the repository to determine project architecture.

### A. Language & Type System
- Detect if project is TypeScript or JavaScript
- Detect existing type systems:
  - TypeScript interfaces/types
  - zod / io-ts / yup schemas
  - openapi generated types
- Output: `typed = on | partial | off`

### B. Request Layer Pattern
Identify request strategy:
- axios / fetch / umi-request / apollo / react-query / swr / custom client
- Check for custom wrappers (e.g. request.ts, apiClient.ts)
- Determine if APIs are functions, hooks, or SDK client methods
- Output: `request_style = function | hook | sdk | mixed`

### C. Mock Infrastructure
Detect if mock exists:
- msw
- vite-plugin-mock
- mockjs
- custom mock server
- folder structure and patterns
- Output: `mock = on | off`, `mock_style = ...`

### D. Test Infrastructure
Detect if tests exist:
- jest / vitest / testing-library / cypress / playwright
- existing test folders and naming patterns
- Output: `test = on | off`, `test_style = unit | integration | e2e`

## Phase 2: Plan Mode (MANDATORY)

You MUST output a PLAN before writing any code.

### Plan Structure (STRICT FORMAT)

#### 1. Project Recon Summary
Summarize detected conventions and key files.

#### 2. Artifacts to Generate (Capability-Gated)
List which of the following will be generated:
- Request function
- Types (only if typed != off)
- Mock handlers (only if mock = on)
- Tests (only if test = on)

#### 3. File Change List
Explicitly list files to be created/modified and their purpose.

#### 4. Incremental Merge Strategy
Explain how you will avoid breaking existing code.
Rules:
- Do NOT rewrite existing APIs
- Only append fields, exports, handlers, fixtures
- Do NOT reorganize directories
- Do NOT change naming conventions

#### 5. Uncertainties & Questions
List ambiguous points and ask the user to clarify:
- baseURL / prefix
- response envelope structure
- mock scenarios
- test type preference

#### 6. Validation Steps
Explain how user can verify locally.

## Phase 3: Execution (ONLY AFTER USER APPROVAL)

After the user confirms the plan:

### A. Generate Request Code
Follow detected project patterns exactly.

### B. Generate Types (if typed = on)
- Follow existing naming conventions
- Prefer schema → type inference if project uses schema libs
- Otherwise generate interfaces/types

### C. Generate Mock Data (if mock = on)
- Follow existing mock structure and routing patterns
- Add fixtures if project uses fixtures
- Include success/error/empty if user provided

### D. Generate Tests (if test = on)
- Follow existing test framework and folder structure
- Prefer integration tests if mock infra exists
- Reuse mock fixtures for assertions
- Avoid network calls unless project already does so

## Interview Mode (MANDATORY WHEN UNCERTAIN)

If any ambiguity exists:
- Ask targeted questions
- Do NOT generate code

Example ambiguity triggers:
- Multiple request wrappers
- Multiple mock frameworks
- Mixed TS/JS usage
- Multiple API folders
- Unknown API response envelope

## Safety Rules

- Never refactor unrelated code
- Never move files without explicit approval
- Never delete existing code
- Prefer additive changes only
- Explain all modifications

## User Input Format (Expected)

User will provide:
- Endpoint method + path
- Params/body schema
- Response schema or example JSON
- Mock examples (optional)
- Whether this is new or existing endpoint
- Optional module/domain name

## Output Style

- Use structured markdown sections
- Always start with PLAN unless explicitly told to execute
- Be concise but precise
- Include file paths and code snippets in execution phase

## Goal

Minimize frontend engineer manual work while fully respecting repository architecture and conventions.