API Documentation Generator Overview Automatically 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. Perfect for REST APIs, GraphQL APIs, and WebSocket APIs. When to Use This Skill Use when you need to document a new API Use when updating existing API documentation Use when your API lacks clear documentation Use when onboarding new developers to your API Use when preparing API documentation for external users Use when creating OpenAPI/Swagger specifications How It Works Step 1: Analyze the API Structure First, I'll examine your API codebase to understand: Available endpoints and routes HTTP methods (GET, POST, PUT, DELETE, etc.) Request parameters and body structure Response formats and status codes Authentication and authorization requirements Error handling patterns Step 2: Generate Endpoint Documentation For each endpoint, I'll create documentation including: Endpoint Details: HTTP method and URL path Brief description of what it does Authentication requirements Rate limiting information (if applicable) Request Specification: Path parameters Query parameters Request headers Request body schema (with types and validation rules) Response Specification: Success response (status code + body structure) Error responses (all possible error codes) Response headers Code Examples: cURL command JavaScript/TypeScript (fetch/axios) Python (requests) Other languages as needed Step 3: Add Usage Guidelines I'll include: Getting started guide Authentication setup Common use cases Best practices Rate limiting details Pagination patterns Filtering and sorting options Step 4: Document Error Handling Clear error documentation including: All possible error codes Error message formats Troubleshooting guide Common error scenarios and solutions Step 5: Create Interactive Examples Where possible, I'll provide: Postman collection OpenAPI/Swagger specification Interactive code examples Sample responses Examples Example 1: REST API Endpoint Documentation
Create User
Creates a new user account.
**
Endpoint:
**
POST /api/v1/users
**
Authentication:
**
Required (Bearer token)
**
Request Body:
**
```json
{
"email": "user@example.com", // Required: Valid email address
"password": "SecurePass123!", // Required: Min 8 chars, 1 uppercase, 1 number
"name": "John Doe", // Required: 2-50 characters
"role": "user" // Optional: "user" or "admin" (default: "user")
}
```
**
Success Response (201 Created):
**
```json
{
"id": "usr_1234567890",
"email": "user@example.com",
"name": "John Doe",
"role": "user",
"createdAt": "2026-01-20T10:30:00Z",
"emailVerified": false
}
```
**
Error Responses:
**
-
400 Bad Request
- Invalid input data
```json
{
"error": "VALIDATION_ERROR",
"message": "Invalid email format",
"field": "email"
}
```
-
409 Conflict
- Email already exists
```json
{
"error": "EMAIL_EXISTS",
"message": "An account with this email already exists"
}
```
-
401 Unauthorized
- Missing or invalid authentication token
**
Example Request (cURL):
**
```bash
curl -X POST https://api.example.com/api/v1/users \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123!",
"name": "John Doe"
}'
```
**
Example Request (JavaScript):
**
```javascript
const response = await fetch('https://api.example.com/api/v1/users', {
method: 'POST',
headers: {
'Authorization':
Bearer ${token}
,
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'user@example.com',
password: 'SecurePass123!',
name: 'John Doe'
})
});
const user = await response.json();
console.log(user);
```
**
Example Request (Python):
**
```python
import requests
response = requests.post(
'https://api.example.com/api/v1/users',
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
},
json={
'email': 'user@example.com',
'password': 'SecurePass123!',
'name': 'John Doe'
}
)
user = response.json()
print(user)
```
Example 2: GraphQL API Documentation
User Query Fetch user information by ID. ** Query: ** ```graphql query GetUser($id: ID!) { user(id: $id) { id email name role createdAt posts { id title publishedAt } } } ``` ** Variables: ** ```json { "id": "usr_1234567890" } ``` ** Response: ** ```json { "data": { "user": { "id": "usr_1234567890", "email": "user@example.com", "name": "John Doe", "role": "user", "createdAt": "2026-01-20T10:30:00Z", "posts": [ { "id": "post_123", "title": "My First Post", "publishedAt": "2026-01-21T14:00:00Z" } ] } } } ``` ** Errors: ** ```json { "errors": [ { "message": "User not found", "extensions": { "code": "USER_NOT_FOUND", "userId": "usr_1234567890" } } ] } ``` Example 3: Authentication Documentation
Authentication All API requests require authentication using Bearer tokens.
Getting a Token
**
Endpoint:
**
POST /api/v1/auth/login
**
Request:
**
```json
{
"email": "user@example.com",
"password": "your-password"
}
```
**
Response:
**
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"refreshToken": "refresh_token_here"
}
```
Using the Token Include the token in the Authorization header: ``` Authorization: Bearer YOUR_TOKEN ```
Token Expiration
Tokens expire after 1 hour. Use the refresh token to get a new access token:
**
Endpoint:
**
POST /api/v1/auth/refresh
**
Request:
**
```json
{
"refreshToken": "refresh_token_here"
}
```
Best Practices
✅ Do This
Be Consistent
- Use the same format for all endpoints
Include Examples
- Provide working code examples in multiple languages
Document Errors
- List all possible error codes and their meanings
Show Real Data
- Use realistic example data, not "foo" and "bar"
Explain Parameters
- Describe what each parameter does and its constraints
Version Your API
- Include version numbers in URLs (/api/v1/)
Add Timestamps
- Show when documentation was last updated
Link Related Endpoints
- Help users discover related functionality
Include Rate Limits
- Document any rate limiting policies
Provide Postman Collection
- Make it easy to test your API
❌ Don't Do This
Don't Skip Error Cases
- Users need to know what can go wrong
Don't Use Vague Descriptions
- "Gets data" is not helpful
Don't Forget Authentication
- Always document auth requirements
Don't Ignore Edge Cases
- Document pagination, filtering, sorting
Don't Leave Examples Broken
- Test all code examples
Don't Use Outdated Info
- Keep documentation in sync with code
Don't Overcomplicate
- Keep it simple and scannable
Don't Forget Response Headers
- Document important headers
Documentation Structure
Recommended Sections
Introduction
What the API does
Base URL
API version
Support contact
Authentication
How to authenticate
Token management
Security best practices
Quick Start
Simple example to get started
Common use case walkthrough
Endpoints
Organized by resource
Full details for each endpoint
Data Models
Schema definitions
Field descriptions
Validation rules
Error Handling
Error code reference
Error response format
Troubleshooting guide
Rate Limiting
Limits and quotas
Headers to check
Handling rate limit errors
Changelog
API version history
Breaking changes
Deprecation notices
SDKs and Tools
Official client libraries
Postman collection
OpenAPI specification
Common Pitfalls
Problem: Documentation Gets Out of Sync
Symptoms:
Examples don't work, parameters are wrong, endpoints return different data
Solution:
Generate docs from code comments/annotations
Use tools like Swagger/OpenAPI
Add API tests that validate documentation
Review docs with every API change
Problem: Missing Error Documentation
Symptoms:
Users don't know how to handle errors, support tickets increase
Solution:
Document every possible error code
Provide clear error messages
Include troubleshooting steps
Show example error responses
Problem: Examples Don't Work
Symptoms:
Users can't get started, frustration increases
Solution:
Test every code example
Use real, working endpoints
Include complete examples (not fragments)
Provide a sandbox environment
Problem: Unclear Parameter Requirements
Symptoms:
Users send invalid requests, validation errors
Solution:
Mark required vs optional clearly
Document data types and formats
Show validation rules
Provide example values
Tools and Formats
OpenAPI/Swagger
Generate interactive documentation:
openapi
:
3.0.0
info
:
title
:
My API
version
:
1.0.0
paths
:
/users
:
post
:
summary
:
Create a new user
requestBody
:
required
:
true
content
:
application/json
:
schema
:
$ref
:
'#/components/schemas/CreateUserRequest'
Postman Collection
Export collection for easy testing:
{
"info"
:
{
"name"
:
"My API"
,
"schema"
:
"https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
}
,
"item"
:
[
{
"name"
:
"Create User"
,
"request"
:
{
"method"
:
"POST"
,
"url"
:
"{{baseUrl}}/api/v1/users"
}
}
]
}