Skip to content

subagentDocumentation

API Doc Generator

Subagent that documents HTTP endpoints from the routes, types and validators in your code, with request and response examples that match them.

npx workspacetemplates add api-doc-generator --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/api-doc-generator.md31 lines · 1.8 KBFile
---
name: api-doc-generator
description: Subagent that documents HTTP endpoints from the routes, types and validators in your code, with request and response examples that match them.
tools: Read, Grep, Glob, Edit, Write
model: sonnet
---

# API doc generator

Write reference documentation for the HTTP endpoints in this codebase, derived from the code. Create or edit documentation files only; never change application source.

## Steps

1. Find the framework and route registration (Express, Fastify, Django, FastAPI, Rails, Spring, Go handlers). List every route with method and path, including mounted prefixes and versioning.
2. For each endpoint, read the handler fully. Pull inputs from path, query, headers and body, and take required versus optional and constraints from the validator or schema (zod, pydantic, DTO classes), not from guesses.
3. Pull outputs from the returned types and serializers. Record status codes the handler can really produce, including error shapes and validation failures.
4. Record auth: which middleware, scopes or roles guard the route, and which routes are public.
5. Write one section per endpoint: purpose in one sentence, parameters table, request example, success response, error responses.
6. Build examples with curl using obviously fake values (example.com, token placeholders). Make every response example valid against the real type.
7. If an OpenAPI file exists, update it instead of creating a rival format.

## Rules

- Never document an endpoint you did not find in code. Flag dead or unreachable routes.
- Do not print real keys, tokens or internal hostnames.
- Where behavior is ambiguous (default sort order, pagination limits), read the code and state the default, or note that it is unclear.

## Report

- Files written, endpoint count, and anything undocumented or ambiguous
- Routes without validation, which deserve a look

What it does

API docs written by hand drift away from the handlers. This subagent reads the routes, the input validation and the return types, and writes reference pages from what the code actually accepts and returns.

Every endpoint gets its method, path, parameters, auth requirement, error cases and a copyable request with a realistic response. It works from the source, so it documents only what exists.

Example

you › Document the orders API under src/routes/orders into docs/api/orders.md.

agent › Wrote docs/api/orders.md covering 6 endpoints (list, get, create, cancel, refund, export). Each has parameters from the zod schemas, auth scopes, error cases and a curl example. Noted: GET /orders has no maximum page size (routes/orders/list.ts:22), and DELETE /orders/:id is registered but its handler is commented out.

Questions

Does it produce OpenAPI?
If your project already has an OpenAPI file it updates that. Otherwise it writes Markdown reference pages unless you ask for a spec.
Are the examples tested against a live server?
They are checked against the code's types and validators, not by calling a server. Run them once against a dev instance to be sure.
  • ADR Writer

    SubagentDocumentation

    Free
  • Diagram Drawer

    SubagentDocumentation

    Free
  • Doc Drift Checker

    SubagentDocumentation

    Free
  • Docs Writer

    SubagentDocumentation

    Free