api-doc

Generate API Documentation

Analyze the project's backend source code to produce a complete OpenAPI 3.0.0 specification and save it to docs/openapi.yaml (or the path provided in $ARGUMENTS if specified).

Step 1 — Detect Framework and Project Info

Read package.json:

• Extract name, version, description fields
• Detect the framework from dependencies:
  • express → Express.js
  • fastify → Fastify
  • koa → Koa.js
  • @hapi/hapi → Hapi.js
  • None found → treat as Generic HTTP API

Step 2 — Read the Main Entry File

Search for and read the first match from (in order): src/index.js, src/app.js, src/server.js, index.js, app.js, server.js

Detect:

• PORT value (e.g. process.env.PORT || 3000)
• Route prefixes (e.g. app.use("/api/v1", ...) → base path /api/v1)
• Auth middleware usage (e.g. verifyToken, authenticate, authMiddleware, passport)
• All registered router prefixes

Step 3 — Discover Route Files

Use Glob to find route files:

• **/routes/**/*.{js,ts}
• **/router/**/*.{js,ts}
• **/controllers/**/*.{js,ts}
• **/api/**/*.{js,ts} (exclude node_modules)

Read each route file and extract:

HTTP Methods and Paths:

• router.get("/path", ...) → GET /path
• router.post("/path", ...) → POST /path
• router.put("/:id", ...) → PUT /{id}
• router.patch("/:id", ...) → PATCH /{id}
• router.delete("/:id", ...) → DELETE /{id}

Path Parameters:

• :id → {id} (integer, required)
• :slug → {slug} (string, required)
• :userId → {userId} (string, required)

Request Body:

• Look at req.body destructuring: const { email, password } = req.body
• If validation exists (joi, zod, yup), read the schema
• Extract field names and types

Response Structure:

• Look at res.json({...}) output shapes
• Status codes: res.status(201), res.status(404), etc.
• Extract response object fields

Auth Protection:

• Does the route handler have middleware? router.get("/", authMiddleware, handler)
• If the middleware name relates to auth → this endpoint is protected