---
name: api-documentation
description: >-
  Generates comprehensive OpenAPI-compatible REST API documentation from source code
  and route definitions. Use when documenting APIs, generating endpoint references,
  or creating developer onboarding docs for HTTP services.
  NOT for internal architecture docs, database schema docs, or CLI tool documentation.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---
## Identity & Scope
**Executor:** either  **Model tier:** haiku
**Scope:** API route files, controller/handler code, request/response schemas, existing OpenAPI specs
**Off-limits:** Modifying application code, calling live APIs, writing tests
### Hard Rules
- No credentials in output or git — ever
- No spending money without explicit user approval
- No deleting files — archive first, 48hr hold
- No killing processes without explicit instruction
- Report completion to boss via structured output
## Essential Principles
1. **Start from developer goals, not endpoints** — Group by use case ("Authentication", "Data Management"), not by HTTP method. Guards against: unusable reference dumps.
2. **Document errors first** — Every endpoint must include error responses. Developers debug errors more than they handle success. Guards against: incomplete docs.
3. **Show runnable examples** — Every endpoint needs a copy-pasteable curl example. Guards against: abstract descriptions.
4. **Verify against source code** — Cross-reference every documented endpoint against actual route definitions. Guards against: hallucinated endpoints.
## When to Use
- Documenting REST API endpoints for external or internal developers
- Generating OpenAPI/Swagger specifications from source code
- Creating API quickstart guides for developer onboarding
- Updating stale API docs after endpoint changes
- "Generate API docs" / "Write OpenAPI spec" / "Document this service"
## When NOT to Use
- Documenting CLI tools — use a dedicated CLI docs skill instead
- Writing database schema documentation — use data modeling docs instead
- Creating system architecture overviews — use `system-design` instead
- Generating SDK/client library docs — use code documentation tools instead
## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "I'll skip error responses since happy path is documented" | Error docs are most-used — developers hit errors more than success |
| "I'll infer parameter types from names instead of reading source" | Guessed types break real integrations |
| "One generic example covers all endpoints" | Each endpoint has different parameters; generic examples teach nothing |
| "I'll document the routes I found without checking for more" | Missing endpoints means incomplete docs |
## Workflow
### Phase 1: Discovery
**Entry:** User has specified a codebase or service to document
**Actions:**
1. Glob for route definition files (`**/routes/**`, `**/controllers/**`, `**/*router*`)
2. Grep for HTTP method decorators/handlers (`@app.get`, `@router.post`, `app.use`)
3. Identify request/response schema files or type definitions
4. List all unique endpoints with their HTTP methods
**Exit:** Complete endpoint inventory with file locations
### Phase 2: Schema Extraction
**Entry:** Endpoint inventory exists
**Actions:**
1. Read each route handler to extract parameter names, types, and validation rules
2. Read request body schemas (Pydantic models, JSON Schema, TypeScript interfaces)
3. Read response schemas and status codes from return statements and error handlers
4. Map authentication/authorization requirements per endpoint
**Exit:** Structured data for every endpoint: method, path, params, request body, responses, auth
### Phase 3: Documentation Generation
**Entry:** All endpoint schemas extracted
**Actions:**
1. Group endpoints by use case (not by file or HTTP method)
2. Write each endpoint doc: description, parameters table, request body, response examples, error codes
3. Generate a curl example for each endpoint using realistic sample data
4. Add a quickstart section showing the 3 most common workflows
**Exit:** Complete documentation draft in markdown
### Phase 4: Verification
**Entry:** Documentation draft complete
**Actions:**
1. Cross-reference every documented endpoint against the source code inventory from Phase 1
2. Verify no endpoints are missing from the documentation
3. Confirm every endpoint has: method, path, description, parameters, response, curl example, error codes
4. Validate parameter types match source code definitions
**Exit:** All checks pass — output results
## Output Format
```json
{
  "skill": "api-documentation",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Documented 14 endpoints across 4 use-case groups for the Memory API",
  "findings": [
    {"item": "POST /api/memory/store", "severity": "info", "detail": "5 params, 3 response codes, curl example included"},
    {"item": "Missing schema for GET /api/health", "severity": "low", "detail": "No response type in source — documented with observed response"}
  ],
  "artifacts": ["docs/api-reference.md"],
  "errors": [],
  "elapsed_seconds": 45.2
}
```
### Bad Example
```json
{"skill": "api-documentation", "status": "completed", "summary": "Documented the API", "findings": []}
```
Wrong: No specifics, no artifact path, empty findings gives the boss zero information.
## Escalation Triggers
STOP and report to boss (do NOT guess) when:
- [ ] Credentials, API keys, or secrets found in source code
- [ ] No identifiable route definitions or HTTP handlers exist
- [ ] Failed to parse route definitions after 3 search strategies
- [ ] Endpoints reference external services you cannot inspect
- [ ] More than 30% of endpoints have no discernible schema
- [ ] Must run the application to discover dynamic routes

Escalate as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`
## Success Criteria
- [ ] Every endpoint in the source code is documented
- [ ] Each endpoint has: method, path, description, parameters, responses, curl example, error codes
- [ ] Endpoints grouped by use case, not by file or method
- [ ] Parameter types match source code definitions
- [ ] Output matches the JSON format above
- [ ] No escalation triggers hit (or all reported)
- [ ] Results reported to boss via structured output
