api-documentation

# API Documentation Skill

Standards for documenting REST and GraphQL APIs.

## REST API Documentation

### Endpoint Format

```markdown
## Endpoint Name

Brief description of what this endpoint does.

**Method:** `GET` | `POST` | `PUT` | `PATCH` | `DELETE`
**Path:** `/api/v1/resource/:id`
**Auth:** Bearer token | API key | None

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| id | string | Resource ID |

### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| page | integer | No | 1 | Page number |
| limit | integer | No | 20 | Items per page |
| sort | string | No | -createdAt | Sort field |

### Request Body

\`\`\`json
{
  "field1": "value",
  "field2": 123
}
\`\`\`

### Response

**Success (200 OK)**

\`\`\`json
{
  "data": { ... },
  "meta": { ... }
}
\`\`\`

**Errors**

| Status | Code | Description |
|--------|------|-------------|
| 400 | VALIDATION_ERROR | Invalid input |
| 404 | NOT_FOUND | Resource not found |
```

### Authentication Section

```markdown
# Authentication

All API requests require authentication via one of:

## Bearer Token (Recommended)

\`\`\`bash
curl -H "Authorization: Bearer <token>" https://api.example.com/v1/users
\`\`\`

Tokens expire after 1 hour. Use the refresh token to obtain a new access token.

## API Key

\`\`\`bash
curl -H "X-API-Key: <api-key>" https://api.example.com/v1/users
\`\`\`

API keys don't expire but can be revoked in the dashboard.

## OAuth 2.0

For third-party integrations:

1. Redirect to `/oauth/authorize`
2. User grants permission
3. Receive authorization code
4. Exchange code for tokens
```

### Pagination Documentation

```markdown
# Pagination

List endpoints return paginated results.

## Request Parameters

| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| page | integer | 1 | - | Page number (1-indexed) |
| limit | integer |