API Documentation Generator

1---
2name: api-documentation-generator
3description: "Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices"
4---
5 
6# API Documentation Generator
7 
8## Overview
9 
10Automatically generate clear, comprehensive API documentation from your codebase. This skill helps you create professional documentation that includes endpoint descriptions, request/response examples, authentication details, error handling, and usage guidelines.
11 
12Perfect for REST APIs, GraphQL APIs, and WebSocket APIs.
13 
14## When to Use This Skill
15 
16- Use when you need to document a new API
17- Use when updating existing API documentation
18- Use when your API lacks clear documentation
19- Use when onboarding new developers to your API
20- Use when preparing API documentation for external users
21- Use when creating OpenAPI/Swagger specifications
22 
23## How It Works
24 
25### Step 1: Analyze the API Structure
26 
27First, I'll examine your API codebase to understand:
28- Available endpoints and routes
29- HTTP methods (GET, POST, PUT, DELETE, etc.)
30- Request parameters and body structure
31- Response formats and status codes
32- Authentication and authorization requirements
33- Error handling patterns
34 
35### Step 2: Generate Endpoint Documentation
36 
37For each endpoint, I'll create documentation including:
38 
39**Endpoint Details:**
40- HTTP method and URL path
41- Brief description of what it does
42- Authentication requirements
43- Rate limiting information (if applicable)
44 
45**Request Specification:**
46- Path parameters
47- Query parameters
48- Request headers
49- Request body schema (with types and validation rules)
50 
51**Response Specification:**
52- Success response (status code + body structure)
53- Error responses (all possible error codes)
54- Response headers
55 
56**Code Examples:**
57- cURL command
58- JavaScript/TypeScript (fetch/axios)
59- Python (requests)
60- Other languages as needed
61 
62### Step 3: Add Usage Guidelines
63 
64I'll include:
65- Getting started guide
66- Authentication setup
67- Common use cases
68- Best practices
69- Rate limiting details
70- Pagination patterns
71- Filtering and sorting options
72 
73### Step 4: Document Error Handling
74 
75Clear error documentation including:
76- All possible error codes
77- Error message formats
78- Troubleshooting guide
79- Common error scenarios and solutions
80 
81### Step 5: Create Interactive Examples
82 
83Where possible, I'll provide:
84- Postman collection
85- OpenAPI/Swagger specification
86- Interactive code examples
87- Sample responses
88 
89## Examples
90 
91### Example 1: REST API Endpoint Documentation
92 
93```markdown
94## Create User
95 
96Creates a new user account.
97 
98**Endpoint:** `POST /api/v1/users`
99 
100**Authentication:** Required (Bearer token)
101 
102**Request Body:**
103\`\`\`json
104{
105  "email": "user@example.com",      // Required: Valid email address
106  "password": "SecurePass123!",     // Required: Min 8 chars, 1 uppercase, 1 number
107  "name": "John Doe",               // Required: 2-50 characters
108  "role": "user"                    // Optional: "user" or "admin" (default: "user")
109}
110\`\`\`
111 
112**Success Response (201 Created):**
113\`\`\`json
114{
115  "id": "usr_1234567890",
116  "email": "user@example.com",
117  "name": "John Doe",
118  "role": "user",
119  "createdAt": "2026-01-20T10:30:00Z",
120  "emailVerified": false
121}
122\`\`\`
123 
124**Error Responses:**
125 
126- `400 Bad Request` - Invalid input data
127  \`\`\`json
128  {
129    "error": "VALIDATION_ERROR",
130    "message": "Invalid email format",
131    "field": "email"
132  }
133  \`\`\`
134 
135- `409 Conflict` - Email already exists
136  \`\`\`json
137  {
138    "error": "EMAIL_EXISTS",
139    "message": "An account with this email already exists"
140  }
141  \`\`\`
142 
143- `401 Unauthorized` - Missing or invalid authentication token
144 
145**Example Request (cURL):**
146\`\`\`bash
147curl -X POST https://api.example.com/api/v1/users \
148  -H "Authorization: Bearer YOUR_TOKEN" \
149  -H "Content-Type: application/json" \
150  -d '{
151    "email": "user@example.com",
152    "password": "SecurePass123!",
153    "name": "John Doe"
154  }'
155\`\`\`
156 
157**Example Request (JavaScript):**
158\`\`\`javascript
159const response = await fetch('https://api.example.com/api/v1/users', {
160  method: 'POST',
161  headers: {
162    'Authorization': `Bearer ${token}`,
163    'Content-Type': 'application/json'
164  },
165  body: JSON.stringify({
166    email: 'user@example.com',
167    password: 'SecurePass123!',
168    name: 'John Doe'
169  })
170});
171 
172const user = await response.json();
173console.log(user);
174\`\`\`
175 
176**Example Request (Python):**
177\`\`\`python
178import requests
179 
180response = requests.post(
181    'https://api.example.com/api/v1/users',
182    headers={
183        'Authorization': f'Bearer {token}',
184        'Content-Type': 'application/json'
185    },
186    json={
187        'email': 'user@example.com',
188        'password': 'SecurePass123!',
189        'name': 'John Doe'
190    }
191)
192 
193user = response.json()
194print(user)
195\`\`\`
196```
197 
198### Example 2: GraphQL API Documentation
199 
200```markdown
201## User Query
202 
203Fetch user information by ID.
204 
205**Query:**
206\`\`\`graphql
207query GetUser($id: ID!) {
208  user(id: $id) {
209    id
210    email
211    name
212    role
213    createdAt
214    posts {
215      id
216      title
217      publishedAt
218    }
219  }
220}
221\`\`\`
222 
223**Variables:**
224\`\`\`json
225{
226  "id": "usr_1234567890"
227}
228\`\`\`
229 
230**Response:**
231\`\`\`json
232{
233  "data": {
234    "user": {
235      "id": "usr_1234567890",
236      "email": "user@example.com",
237      "name": "John Doe",
238      "role": "user",
239      "createdAt": "2026-01-20T10:30:00Z",
240      "posts": [
241        {
242          "id": "post_123",
243          "title": "My First Post",
244          "publishedAt": "2026-01-21T14:00:00Z"
245        }
246      ]
247    }
248  }
249}
250\`\`\`
251 
252**Errors:**
253\`\`\`json
254{
255  "errors": [
256    {
257      "message": "User not found",
258      "extensions": {
259        "code": "USER_NOT_FOUND",
260        "userId": "usr_1234567890"
261      }
262    }
263  ]
264}
265\`\`\`
266```
267 
268### Example 3: Authentication Documentation
269 
270```markdown
271## Authentication
272 
273All API requests require authentication using Bearer tokens.
274 
275### Getting a Token
276 
277**Endpoint:** `POST /api/v1/auth/login`
278 
279**Request:**
280\`\`\`json
281{
282  "email": "user@example.com",
283  "password": "your-password"
284}
285\`\`\`
286 
287**Response:**
288\`\`\`json
289{
290  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
291  "expiresIn": 3600,
292  "refreshToken": "refresh_token_here"
293}
294\`\`\`
295 
296### Using the Token
297 
298Include the token in the Authorization header:
299 
300\`\`\`
301Authorization: Bearer YOUR_TOKEN
302\`\`\`
303 
304### Token Expiration
305 
306Tokens expire after 1 hour. Use the refresh token to get a new access token:
307 
308**Endpoint:** `POST /api/v1/auth/refresh`
309 
310**Request:**
311\`\`\`json
312{
313  "refreshToken": "refresh_token_here"
314}
315\`\`\`
316```
317 
318## Best Practices
319 
320### ✅ Do This
321 
322- **Be Consistent** - Use the same format for all endpoints
323- **Include Examples** - Provide working code examples in multiple languages
324- **Document Errors** - List all possible error codes and their meanings
325- **Show Real Data** - Use realistic example data, not "foo" and "bar"
326- **Explain Parameters** - Describe what each parameter does and its constraints
327- **Version Your API** - Include version numbers in URLs (/api/v1/)
328- **Add Timestamps** - Show when documentation was last updated
329- **Link Related Endpoints** - Help users discover related functionality
330- **Include Rate Limits** - Document any rate limiting policies
331- **Provide Postman Collection** - Make it easy to test your API
332 
333### ❌ Don't Do This
334 
335- **Don't Skip Error Cases** - Users need to know what can go wrong
336- **Don't Use Vague Descriptions** - "Gets data" is not helpful
337- **Don't Forget Authentication** - Always document auth requirements
338- **Don't Ignore Edge Cases** - Document pagination, filtering, sorting
339- **Don't Leave Examples Broken** - Test all code examples
340- **Don't Use Outdated Info** - Keep documentation in sync with code
341- **Don't Overcomplicate** - Keep it simple and scannable
342- **Don't Forget Response Headers** - Document important headers
343 
344## Documentation Structure
345 
346### Recommended Sections
347 
3481. **Introduction**
349   - What the API does
350   - Base URL
351   - API version
352   - Support contact
353 
3542. **Authentication**
355   - How to authenticate
356   - Token management
357   - Security best practices
358 
3593. **Quick Start**
360   - Simple example to get started
361   - Common use case walkthrough
362 
3634. **Endpoints**
364   - Organized by resource
365   - Full details for each endpoint
366 
3675. **Data Models**
368   - Schema definitions
369   - Field descriptions
370   - Validation rules
371 
3726. **Error Handling**
373   - Error code reference
374   - Error response format
375   - Troubleshooting guide
376 
3777. **Rate Limiting**
378   - Limits and quotas
379   - Headers to check
380   - Handling rate limit errors
381 
3828. **Changelog**
383   - API version history
384   - Breaking changes
385   - Deprecation notices
386 
3879. **SDKs and Tools**
388   - Official client libraries
389   - Postman collection
390   - OpenAPI specification
391 
392## Common Pitfalls
393 
394### Problem: Documentation Gets Out of Sync
395**Symptoms:** Examples don't work, parameters are wrong, endpoints return different data
396**Solution:** 
397- Generate docs from code comments/annotations
398- Use tools like Swagger/OpenAPI
399- Add API tests that validate documentation
400- Review docs with every API change
401 
402### Problem: Missing Error Documentation
403**Symptoms:** Users don't know how to handle errors, support tickets increase
404**Solution:**
405- Document every possible error code
406- Provide clear error messages
407- Include troubleshooting steps
408- Show example error responses
409 
410### Problem: Examples Don't Work
411**Symptoms:** Users can't get started, frustration increases
412**Solution:**
413- Test every code example
414- Use real, working endpoints
415- Include complete examples (not fragments)
416- Provide a sandbox environment
417 
418### Problem: Unclear Parameter Requirements
419**Symptoms:** Users send invalid requests, validation errors
420**Solution:**
421- Mark required vs optional clearly
422- Document data types and formats
423- Show validation rules
424- Provide example values
425 
426## Tools and Formats
427 
428### OpenAPI/Swagger
429Generate interactive documentation:
430```yaml
431openapi: 3.0.0
432info:
433  title: My API
434  version: 1.0.0
435paths:
436  /users:
437    post:
438      summary: Create a new user
439      requestBody:
440        required: true
441        content:
442          application/json:
443            schema:
444              $ref: '#/components/schemas/CreateUserRequest'
445```
446 
447### Postman Collection
448Export collection for easy testing:
449```json
450{
451  "info": {
452    "name": "My API",
453    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
454  },
455  "item": [
456    {
457      "name": "Create User",
458      "request": {
459        "method": "POST",
460        "url": "{{baseUrl}}/api/v1/users"
461      }
462    }
463  ]
464}
465```
466 
467## Related Skills
468 
469- `@doc-coauthoring` - For collaborative documentation writing
470- `@copywriting` - For clear, user-friendly descriptions
471- `@test-driven-development` - For ensuring API behavior matches docs
472- `@systematic-debugging` - For troubleshooting API issues
473 
474## Additional Resources
475 
476- [OpenAPI Specification](https://swagger.io/specification/)
477- [REST API Best Practices](https://restfulapi.net/)
478- [GraphQL Documentation](https://graphql.org/learn/)
479- [API Design Patterns](https://www.apiguide.com/)
480- [Postman Documentation](https://learning.postman.com/docs/)
481 
482---
483 
484**Pro Tip:** Keep your API documentation as close to your code as possible. Use tools that generate docs from code comments to ensure they stay in sync!
485