API Documentation Generator

---
name: api-documentation-gen
description: |
  Trigger when the user asks to generate API docs, document endpoints, build
  an OpenAPI spec, or create a reference for their HTTP API. Phrases:
  "document the API", "OpenAPI spec", "API reference", "endpoint docs".
allowed-tools:
  - Read
  - Write
  - Grep
  - Glob
---

# API Documentation Generator

Read an HTTP API's route handlers and produce OpenAPI 3.1 + markdown reference
docs. Works across Express, Fastify, Next.js route handlers, Hono, and FastAPI.

## Prerequisites

- Route handler files present in the repo
- Response types or Zod/Pydantic schemas available where possible

## Steps

1. **Find route files.** Use framework-specific heuristics:
   - Express/Fastify: grep for `app.get|app.post|router.\w+`
   - Next.js App Router: `app/**/route.ts`
   - Hono: `app.\w+\(` in a Hono instance
   - FastAPI: `@app.get|@router.get|@app.post` decorators

2. **Extract per-endpoint metadata:**
   - HTTP method and path
   - Path parameters and their types
   - Request body schema (prefer declared Zod/Pydantic over inference)
   - Response schema and status codes
   - Authentication requirement (look for middleware/guards)

3. **Generate OpenAPI 3.1 JSON.** Write to `openapi.json` at repo root.
   Include `info`, `paths`, `components.schemas`, and `components.securitySchemes`.

4. **Generate markdown reference.** Write to `docs/api-reference.md` with:
   - One section per endpoint, grouped by resource
   - Example request and response per endpoint (use realistic values)
   - Error response table
   - Auth section at the top

5. **Validate the OpenAPI spec:**

   ```bash
   npx @redocly/cli lint openapi.json
   ```

   Fix any errors before reporting complete.

## Guidelines

- Prefer declared schemas over inference. If the route handler uses Zod,
  read the schema directly and convert to JSON Schema.
- Do not invent endpoints. Document only what the code exposes.
- Note authentication clearly. If a route is unauthenticated, say so.
- Group paths logically (`/users/*`, `/posts/*`) in the markdown.

## Output

- `openapi.json` - machine-readable spec
- `docs/api-reference.md` - human-readable reference
- Console summary of endpoint count by method