API Documentation Generator

Expert assistance for creating comprehensive API documentation in Confluence.

When to Use This Skill

• Documenting new API endpoints
• Creating API reference pages
• Converting OpenAPI/Swagger specs to Confluence
• User mentions: API, endpoints, REST, GraphQL, documentation
• After implementing new API features

API Documentation Structure

Complete API Page Template

# [API Name] API

## Overview
Brief description of what this API does and its purpose.

## Base URL

https://api.example.com/v1

## Authentication
How to authenticate with this API.

## Endpoints

### GET /resource
Brief description of what this endpoint does.

#### Parameters
[Parameter table]

#### Request Example
[Code block with example]

#### Response
[Success response example]

#### Error Codes
[Error table]

## Rate Limiting
API rate limit information.

## Changelog
Version history and changes.

Endpoint Documentation

Standard Sections

1. Endpoint Header

### POST /api/users
Create a new user account

2. Description

Creates a new user account with the provided information.
Sends a verification email to the user's address.

**Permissions**: Requires `admin` role
**Rate Limit**: 10 requests per minute

3. Parameters Table

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	User ID (UUID format)
version	integer	No	API version (default: 1)

Query Parameters

Parameter	Type	Required	Description	Default
page	integer	No	Page number	1
limit	integer	No	Items per page	20
sort	string	No	Sort field	created_at
order	string	No	Sort order (asc/desc)	desc

Request Body

Field	Type	Required	Description	Constraints
email	string	Yes	User email address	Valid email format
username	string	Yes	Username	3-20 alphanumeric chars
password	string	Yes	Password	Min 8 chars, 1 uppercase, 1 number
full_name	string	No	Full name	Max 100 chars
role	string	No	User role	One of: user, admin, moderator

4. Request Example

cURL:

curl -X POST https://api.example.com/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "email": "user@example.com",
    "username": "johndoe",
    "password": "SecurePass123",
    "full_name": "John Doe",
    "role": "user"
  }'

JavaScript (fetch):

const response = await fetch('https://api.example.com/v1/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    username: 'johndoe',
    password: 'SecurePass123',
    full_name: 'John Doe',
    role: 'user'
  })
});

const data = await response.json();
console.log(data);

Python (requests):

import requests

url = "https://api.example.com/v1/users"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "email": "user@example.com",
    "username": "johndoe",
    "password": "SecurePass123",
    "full_name": "John Doe",
    "role": "user"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

5. Response Examples

Success Response (201 Created):

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "username": "johndoe",
    "full_name": "John Doe",
    "role": "user",
    "email_verified": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Response Fields:

Field	Type	Description
id	string	Unique user identifier (UUID)
email	string	User's email address
username	string	Username
full_name	string	User's full name
role	string	User's role
email_verified	boolean	Email verification status
created_at	string	Account creation timestamp (ISO 8601)
updated_at	string	Last update timestamp (ISO 8601)

6. Error Responses

Status Code	Error Code	Description	Resolution
400	INVALID_EMAIL	Email format is invalid	Provide valid email address
400	WEAK_PASSWORD	Password doesn't meet requirements	Use min 8 chars, 1 uppercase, 1 number
400	USERNAME_TAKEN	Username already exists	Choose different username
401	UNAUTHORIZED	Missing or invalid API key	Include valid Authorization header
403	FORBIDDEN	Insufficient permissions	Requires admin role
429	RATE_LIMIT_EXCEEDED	Too many requests	Wait before retrying
500	INTERNAL_ERROR	Server error	Contact support if persists

Error Response Format:

{
  "status": "error",
  "error": {
    "code": "USERNAME_TAKEN",
    "message": "The username 'johndoe' is already in use",
    "details": {
      "field": "username",
      "value": "johndoe"
    }
  }
}

Authentication Documentation

API Key Authentication

## Authentication

All API requests require authentication using an API key.

### Obtaining an API Key
1. Log in to your account
2. Navigate to Settings > API Keys
3. Click "Generate New Key"
4. Store the key securely (shown only once)

### Using the API Key

Include the API key in the `Authorization` header:

Authorization: Bearer YOUR_API_KEY

**Example**:
```bash
curl -H "Authorization: Bearer sk_test_abc123..." \
  https://api.example.com/v1/users

Security Best Practices

• Never commit API keys to version control
• Rotate keys regularly (every 90 days)
• Use environment variables for key storage
• Different keys for development/production

### OAuth 2.0 Documentation

```markdown
## Authentication

This API uses OAuth 2.0 for authentication.

### Authorization Flow

1. **Redirect user to authorization URL**:

https://api.example.com/oauth/authorize? client_id=YOUR_CLIENT_ID& redirect_uri=YOUR_REDIRECT_URI& response_type=code& scope=read write

2. **User authorizes your app**

3. **Receive authorization code**:

https://your-redirect-uri?code=AUTH_CODE

4. **Exchange code for access token**:
```bash
curl -X POST https://api.example.com/oauth/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTH_CODE" \
  -d "grant_type=authorization_code"

5. Use access token in requests:

Authorization: Bearer ACCESS_TOKEN

Scopes

Scope	Description
read	Read access to resources
write	Create and update resources
delete	Delete resources
admin	Full administrative access

## Rate Limiting Documentation

```markdown
## Rate Limiting

API requests are rate limited to ensure fair usage.

### Limits

| Tier | Requests per minute | Requests per day |
|------|-------------------|------------------|
| Free | 60 | 10,000 |
| Pro | 600 | 100,000 |
| Enterprise | Unlimited | Unlimited |

### Rate Limit Headers

Each response includes rate limit information:

X-RateLimit-Limit: 60 X-RateLimit-Remaining: 45 X-RateLimit-Reset: 1642247400

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Total requests allowed in window |
| `X-RateLimit-Remaining` | Requests remaining in window |
| `X-RateLimit-Reset` | Unix timestamp when limit resets |

### Handling Rate Limits

When rate limited, you'll receive a `429 Too Many Requests` response:

```json
{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "retry_after": 42
  }
}

Best practices:

• Monitor X-RateLimit-Remaining header
• Implement exponential backoff
• Cache responses when possible
• Use webhooks instead of polling

## Pagination Documentation

```markdown
## Pagination

List endpoints return paginated results.

### Request Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Page number (1-indexed) |
| `limit` | integer | 20 | Items per page (max 100) |

### Example Request

```bash
GET /api/users?page=2&limit=50

Response Format

{
  "data": [
    {...},
    {...}
  ],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total_pages": 10,
    "total_items": 487,
    "has_next": true,
    "has_prev": true
  },
  "links": {
    "first": "/api/users?page=1&limit=50",
    "prev": "/api/users?page=1&limit=50",
    "next": "/api/users?page=3&limit=50",
    "last": "/api/users?page=10&limit=50"
  }
}

## From OpenAPI/Swagger Spec

### Converting OpenAPI to Confluence

When given an OpenAPI specification:

1. **Extract metadata**:
   - API title and version
   - Base URL
   - Contact information

2. **Parse endpoints**:
   - HTTP method and path
   - Summary and description
   - Parameters (path, query, body)
   - Response schemas
   - Status codes

3. **Generate examples**:
   - Request examples in multiple languages
   - Response examples with real data
   - Error examples

4. **Add documentation**:
   - Authentication requirements
   - Rate limiting
   - Versioning strategy

### Example: OpenAPI → Confluence

**OpenAPI Spec**:
```yaml
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

Generated Confluence Page:

### GET /users/{id}
Retrieve user information by user ID.

#### Parameters

| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| `id` | string | path | Yes | User ID |

#### Response (200 OK)
```json
{
  "id": "123",
  "username": "johndoe",
  "email": "john@example.com"
}

Errors

• 404 Not Found: User with specified ID does not exist

## Code from Implementation

### Extracting API Docs from Code

When documenting from actual code:

1. **Identify endpoints**:
   - Search for route definitions
   - Extract HTTP methods and paths

2. **Parse parameters**:
   - Look for request validation
   - Find query/body parameter definitions

3. **Extract responses**:
   - Identify return statements
   - Find response status codes

4. **Add context**:
   - Code comments
   - Function documentation
   - Type definitions

### Example: Express.js → Confluence

**Code**:
```javascript
/**
 * Create a new user
 * @route POST /api/users
 * @param {string} email - User email
 * @param {string} username - Username
 * @returns {object} Created user object
 */
app.post('/api/users', async (req, res) => {
  const { email, username } = req.body;

  if (!email || !username) {
    return res.status(400).json({
      error: 'Email and username are required'
    });
  }

  const user = await db.users.create({ email, username });

  res.status(201).json({ data: user });
});

Generated Documentation:

### POST /api/users
Create a new user account.

#### Request Body
```json
{
  "email": "user@example.com",
  "username": "johndoe"
}

Response (201 Created)

{
  "data": {
    "id": "123",
    "email": "user@example.com",
    "username": "johndoe"
  }
}

Errors

• 400 Bad Request: Email and username are required

## Best Practices

### 1. Clear Naming
- Use descriptive endpoint names
- Follow REST conventions (GET, POST, PUT, DELETE)
- Consistent resource naming

### 2. Complete Examples
- Show real, working examples
- Include authentication
- Cover common use cases
- Multiple languages (cURL, JavaScript, Python)

### 3. Error Documentation
- Document all possible errors
- Include error codes
- Explain how to resolve errors
- Show error response format

### 4. Versioning
- Document version in URL (`/v1/users`)
- Note deprecated endpoints
- Maintain changelog
- Migration guides between versions

### 5. Security
- Authentication requirements clear
- Note permissions needed
- Security best practices
- Data sensitivity warnings

## Confluence Organization

### API Documentation Structure

API Documentation Space ├── Overview │ ├── Getting Started │ ├── Authentication │ ├── Rate Limiting │ └── Versioning ├── Endpoints │ ├── Users API │ │ ├── GET /users │ │ ├── POST /users │ │ ├── GET /users/{id} │ │ ├── PUT /users/{id} │ │ └── DELETE /users/{id} │ ├── Posts API │ └── Comments API ├── Reference │ ├── Error Codes │ ├── Status Codes │ └── Data Models └── Guides ├── Quick Start ├── Common Patterns └── Best Practices

## How I'll Help

When creating API documentation, I will:

1. **Analyze the API**:
   - Read code or OpenAPI spec
   - Identify endpoints and methods
   - Extract parameters and responses

2. **Structure documentation**:
   - Create logical sections
   - Organize by resource or functionality
   - Add navigation and links

3. **Generate examples**:
   - Multiple programming languages
   - Real, working code
   - Common use cases

4. **Add details**:
   - Authentication requirements
   - Error handling
   - Rate limiting
   - Best practices

5. **Create in Confluence**:
   - Convert to ADF format
   - Use proper formatting
   - Add code highlighting
   - Create tables

6. **Maintain**:
   - Update when API changes
   - Add deprecation notices
   - Version documentation

## Example Interaction

**You**: "Document the new payment API I just implemented"

**Me**: "I'll create comprehensive API documentation for the payment API.

[Analyzes code and finds endpoints]

Found endpoints:
- POST /api/payments - Create payment
- GET /api/payments/{id} - Get payment status
- POST /api/payments/{id}/refund - Refund payment

Creating Confluence documentation with:
- Overview and authentication
- Detailed endpoint documentation
- Request/response examples in cURL, JavaScript, Python
- Error codes and handling
- Payment flow diagrams

Which Confluence space should I use?"

**You**: "Space 789012"

**Me**: [Creates comprehensive API documentation]
"Created 'Payment API Documentation' in space 789012!

Includes:
- 3 endpoint pages with full details
- Authentication guide
- Error reference
- Code examples in 3 languages

Link: https://your-domain.atlassian.net/wiki/spaces/789012/pages/..."