api-reference-generator

You are generating API reference documentation from route handler source files. Follow each step in order. ## Step 1 — Discover Route Files If the user specifies a path (e.g. `/api/workflows`), locate the matching route files. If the user asks for "all routes", search for route handler files in: - `app/api/**/route.ts` (Next.js App Router) - `pages/api/**/*.ts` (Next.js Pages Router) - `src/app/api/**/route.ts` - `src/pages/api/**/*.ts` List all route files found before proceeding. ## Step 2 — Analyze Each Route Handler For each route file, read the source and extract: **Endpoint metadata:** - HTTP method(s) exported: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` - Full path: derive from the file path (e.g. `app/api/users/[id]/route.ts` → `/api/users/:id`) - Route segment params: dynamic segments (`[id]`, `[slug]`, `[...rest]`) **Request shape:** - URL query parameters: names, types, required/optional, default values - Path parameters: names and types - Request body: parse `request.json()` calls, Zod schemas, TypeScript interfaces — extract all fields with types - Headers: any required headers (Authorization, Content-Type, custom headers) - Authentication: is the route protected? How (session cookie, Bearer token, API key)? **Response shape:** - Success response: HTTP status code, response body shape (extract from `NextResponse.json(...)` calls or return statements) - Error responses: each error condition, HTTP status code, error body structure - Response headers set explicitly (e.g. Cache-Control, Location) **Business logic summary:** - What does this endpoint do in 1–2 sentences? - Any side effects (sends email, creates DB record, calls external API)? - Rate limiting or special middleware applied? ## Step 3 — Load the Template Read `assets/template.md` from this skill's directory. Use it as the structural template for each endpoint's documentation block. ## Step 4 — Generate the API Reference Write the full API reference document. Follow these rules: - One top-level section per resource (e.g. `## Users`, `## Workflows`, `## Auth`) - Within each resource, one subsection per endpoint method+path combination - Every endpoint entry follows the template from `assets/template.md` - Request and response bodies use JSON code blocks showing a realistic example (not just the schema) - Alongside each example, provide a TypeScript interface or Zod-style type showing the full shape - List every error response the handler can return — don't omit non-200 paths - For authenticated routes, describe exactly what credential is required and where to send it ## Step 5 — Add Reference Sections After all endpoint entries, append: ### Authentication Describe the authentication mechanism(s) used across the API (e.g. session cookies, Bearer tokens, API keys). Include an example of how to authenticate a request. ### Error Response Format Document the standard error response envelope shape used across the API. Example: ```json { "error": "string", "message": "string", "statusCode": 400 } ``` ### Rate Limiting Document any rate limiting (if found in middleware or route handlers). Note limits per route or globally. ### Base URL Note the base URL convention (e.g. `https://yourdomain.com/api` in production, `http://localhost:3000/api` in development). ## Output Format Deliver the full reference as a single Markdown document. Include at the top: ``` <!-- Generated by: api-reference-generator skill Routes analyzed: (list the route files read) Last updated: (today's date) --> ``` After the reference, add an `## Accuracy Notes` section listing: - Any route handlers with missing type annotations that required inference - Any routes skipped and why - Any assumptions made about auth or error shapes