api-documentation-generator（API 文档生成器）

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

Query Parameters

Request Body

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:

6. Error Responses

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**:

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

## 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**:

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"

1. **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

## 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:

{ "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

## 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

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

1. Parse endpoints:

- HTTP method and path - Summary and description - Parameters (path, query, body) - Response schemas - Status codes

1. Generate examples:

- Request examples in multiple languages - Response examples with real data - Error examples

1. Add documentation:

- Authentication requirements - Rate limiting - Versioning strategy

Example: OpenAPI → Confluence

OpenAPI Spec:

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)

{ "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

1. Parse parameters:

- Look for request validation - Find query/body parameter definitions

1. Extract responses:

- Identify return statements - Find response status codes

1. Add context:

- Code comments - Function documentation - Type definitions

Example: Express.js → Confluence

Code:

/**
 * 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

{ "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

1. Structure documentation:

- Create logical sections - Organize by resource or functionality - Add navigation and links

1. Generate examples:

- Multiple programming languages - Real, working code - Common use cases

1. Add details:

- Authentication requirements - Error handling - Rate limiting - Best practices

1. Create in Confluence:

- Convert to ADF format - Use proper formatting - Add code highlighting - Create tables

1. 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/..."