[{"skill":"api-architect","reason":"Architect designs the API, this skill documents what was built"},{"skill":"openapi-spec-writer","reason":"Spec writer creates from scratch, this skill extracts from existing code"},{"skill":"typescript-advanced-patterns","reason":"Generating accurate TypeScript types from route handlers"}]
API Documentation Generator
Extracts API documentation from existing route handler code. Reads your source, infers schemas, and produces OpenAPI specs, TypeScript types, and runnable curl examples -- not from design intent but from actual implementation.
Activation Triggers
Activate on: "generate API docs", "OpenAPI from code", "document endpoints", "API reference", "swagger generation", "endpoint documentation", "create API types", "curl examples for API"
NOT for: API design from scratch --> api-architect | OpenAPI authoring without source code --> openapi-spec-writer | API testing --> test-automation-expert
Core Capabilities
Extract route definitions from Express, Next.js App Router, Next.js Pages API routes, Fastify, and Hono handlers
Infer request/response schemas from TypeScript types, Zod schemas, or runtime validation
Generate OpenAPI 3.0/3.1 specifications with accurate path parameters, query strings, and request bodies
Produce TypeScript type definitions matching the actual API contract
Create curl examples for every endpoint with realistic sample data
Document authentication requirements by tracing middleware chains
Identify rate limiting configuration and document per-endpoint limits
Catalog error responses by analyzing throw/return patterns in handlers
Detect undocumented endpoints (routes that exist but have no JSDoc or schema)
Framework Detection
Before generating anything, identify the framework. The extraction strategy differs significantly.
Express / Express-like
Signals: app.get(), router.post(), express.Router()
Route source: app._router.stack or explicit router files
Middleware chain: app.use() order matters for auth detection
Look for route registration patterns:
router.get('/users/:id', authenticate, getUser) -- middleware before handler means auth required
Signals: fastify.get(), fastify.route(), schema property on route options
Route source: Plugin registration with fastify.register()
Schema: Fastify routes often have JSON Schema already -- extract and convert
Fastify is the easiest framework to document because routes frequently declare their own schemas. Prioritize extracting existing schema.body, schema.response, and schema.querystring before inferring.
Hono
Signals: app.get(), app.post(), Hono(), zValidator()
Route source: Method chaining on Hono instance
Validation: zod-based via zValidator middleware
Hono with zValidator gives you Zod schemas directly. Convert Zod --> JSON Schema --> OpenAPI schema.
Extraction Process
Step 1: Discover Routes
Scan the project for route registration. Do not rely on a single entry point -- frameworks often split routes across files.
Generate one curl per endpoint. Use realistic but obviously fake data.
# GET /api/users/:id -- Fetch a single user
curl -X GET https://api.example.com/api/users/usr_abc123 \
-H "Authorization: Bearer sk_test_..." \
-H "Accept: application/json"# POST /api/users -- Create a new user
curl -X POST https://api.example.com/api/users \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Ada Lovelace",
"email": "ada@example.com",
"role": "member"
}'# GET /api/users -- List users with pagination
curl -X GET "https://api.example.com/api/users?page=1&perPage=20&role=admin" \
-H "Authorization: Bearer sk_test_..." \
-H "Accept: application/json"
Rules for curl examples:
Always include the full URL (use https://api.example.com as base)
Include all required headers
Use -d with formatted JSON for request bodies
Quote URLs that contain query parameters
Show the HTTP method explicitly even for GET
Use sk_test_... for auth tokens (obviously fake)
Use realistic field values, not "string" or "test"
Anti-Patterns
1. Documenting Aspirational APIs
Symptom: Spec describes endpoints that do not exist in code yet
Fix: Only document what the code actually implements. If a planned endpoint is in comments or a spec file but not in handlers, exclude it.
2. Ignoring Middleware Side Effects
Symptom: Docs say endpoint is public when it actually requires auth through a parent middleware
Fix: Trace the full middleware chain from app root to handler. A router.use(auth) above the route definition means all routes below require auth.
3. Assuming Request Body Shape
Symptom: Documenting req.body as any or object because there is no validation
Fix: Infer from usage (property access, destructuring, database calls). Mark as x-inferred: true. Recommend adding Zod validation.
4. Flat Error Documentation
Symptom: Every endpoint lists the same generic "400 Bad Request" without details
Fix: Read each handler's error paths. Document the specific error codes and messages returned. Different validation failures should show different example responses.
5. Stale Generated Docs
Symptom: Spec was generated once and never updated as code changed
Fix: Generate into a well-known path (docs/openapi.yaml). Add a CI check that regenerates and diffs against committed spec. If they diverge, fail the build.
6. Missing Pagination Documentation
Symptom: List endpoints documented without query parameter schemas for pagination
Fix: If the handler supports page, limit, cursor, offset, or similar parameters, document them with defaults and max values.
7. Undocumented File Uploads
Symptom: Multipart/form-data endpoints documented as JSON
Fix: Detect multer, formidable, busboy, or framework-native file handling. Use multipart/form-data content type with proper binary schema.
Quality Checklist
[ ] Every route handler in the codebase has a corresponding OpenAPI operation
[ ] Path parameters match between code and spec (no :id vs {userId} mismatches)
[ ] Request body schemas cover all required and optional fields
[ ] Response schemas match actual JSON structure (verified by reading handler return)
[ ] Authentication requirements match middleware chain analysis
[ ] Rate limit information documented where rate limiting middleware exists
[ ] Error responses cataloged from actual throw/return statements in handlers
[ ] Curl examples execute successfully against a running instance
[ ] TypeScript types compile without errors
[ ] No x-inferred schemas left undocumented (each flagged one has a TODO for proper validation)
[ ] Pagination parameters documented with defaults and maximums
[ ] File upload endpoints use multipart/form-data content type
[ ] OpenAPI spec validates with spectral or swagger-cli lint
[ ] Generated spec committed to a known path for CI diffing
