API Documentation Generator
Reads API source code and generates comprehensive documentation with endpoint descriptions, examples, and schemas.
SKILL.md
---
description: Generate API documentation from source code
allowed-tools: Read, Bash(ls), Bash(cat *), Glob, Write
---
# API Documentation Generator
Generate comprehensive API documentation by reading the actual route handlers, types, and validation schemas.
## Arguments
- `$ARGUMENTS` — path to the API directory or specific endpoint file
## Steps
1. Scan the API directory structure to build a route map.
2. For each endpoint, read the source code and extract:
- HTTP method and path
- Request parameters (path, query, body) with types
- Response shape and status codes
- Authentication requirements
- Rate limiting or other middleware
3. Read validation schemas (Zod, Joi, etc.) to get exact field constraints.
4. Check for existing documentation to understand the preferred format.
## Documentation structure
For each endpoint, generate:
```markdown
## `METHOD /path/to/endpoint`
<One-sentence description of what this endpoint does.>
### Authentication
<Required | Optional | None> — <token type if applicable>
### Request
#### Path Parameters
| Parameter | Type | Description |
|-----------|--------|----------------------|
| id | string | The user's unique ID |
#### Query Parameters
| Parameter | Type | Default | Description |
|-----------|--------|---------|------------------------|
| page | number | 1 | Page number |
| limit | number | 20 | Items per page (max 100)|
#### Request Body
\`\`\`json
{
"email": "user@example.com",
"name": "Jane Doe"
}
\`\`\`
### Response
#### 200 OK
\`\`\`json
{
"data": {
"id": "usr_abc123",
"email": "user@example.com",
"name": "Jane Doe"
},
"meta": {
"requestId": "req_xyz789"
}
}
\`\`\`
#### 400 Bad Request
\`\`\`json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Email is required",
"details": [...]
}
}
\`\`\`
### Example
\`\`\`bash
curl -X POST https://api.example.com/users \\
-H "Authorization: Bearer <token>" \\
-H "Content-Type: application/json" \\
-d '{"email": "user@example.com", "name": "Jane Doe"}'
\`\`\`
```
## Rules
- Generate examples with realistic but clearly fake data (use example.com, Jane Doe, etc.).
- Document ALL status codes the endpoint can return, not just the success case.
- Include curl examples for every endpoint.
- Note deprecated endpoints clearly with a warning banner.
- Group endpoints by resource (users, posts, etc.) and sort methods: GET, POST, PUT, PATCH, DELETE.How It Works
This skill solves the perennial problem of documentation drifting out of sync with code. By reading the actual source code, validation schemas, and middleware, it generates documentation that reflects the true current behavior of the API rather than what someone remembered to write down months ago.
The structured template ensures every endpoint is documented to the same level of detail. The inclusion of error responses alongside success responses is particularly valuable — many API docs only show the happy path, leaving consumers to discover error formats through trial and error.
The curl examples at the end of each endpoint make the documentation immediately testable. A developer can copy-paste the curl command, substitute their token, and verify the endpoint works. This bridges the gap between reading docs and actually using the API.