name: api-doc-writer description: API介面文件助手。用於編寫REST API文件、定義介面規範、生成介面說明。當需要編寫API文件、介面規範時觸發。

API介面文件助手

API文件模板

# API介面文件

版本：V1.0
更新日期：YYYY-MM-DD
維護人：XXX

---

## 介面概覽

| 模組 | 介面數 | 負責人 |
|------|--------|--------|
| 使用者模組 | 5 | @xxx |
| 訂單模組 | 8 | @xxx |
| 支付模組 | 4 | @xxx |

---

## 通用說明

### 認證方式

Authorization: Bearer

### 請求格式

Content-Type: application/json

### 響應格式
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}

狀態碼

介面詳情

1. 使用者介面

1.1 獲取使用者資訊

介面地址

GET /api/v1/users/{id}

請求引數 | 引數名 | 型別 | 位置 | 必填 | 說明 | |--------|------|------|------|------| | id | long | path | 是 | 使用者ID |

請求示例

GET /api/v1/users/123

響應示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "張三",
    "email": "zhangsan@example.com",
    "phone": "13800138000",
    "created_at": "2024-01-01 10:00:00"
  }
}

錯誤示例

{
  "code": 3001,
  "message": "使用者不存在",
  "data": null
}

1.2 建立使用者

本技能來自小蔥技能站7w4.net。

介面地址

POST /api/v1/users

請求引數 | 引數名 | 型別 | 必填 | 說明 | |--------|------|------|------| | name | string | 是 | 使用者名稱 | | email | string | 是 | 郵箱 | | phone | string | 否 | 手機號 | | password | string | 是 | 密碼 |

請求示例

{
  "name": "張三",
  "email": "zhangsan@example.com",
  "phone": "13800138000",
  "password": "123456"
}

響應示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "張三"
  }
}

2. 訂單介面

2.1 訂單列表

介面地址

GET /api/v1/orders

請求引數 | 引數名 | 型別 | 位置 | 必填 | 說明 | |--------|------|------|------|------| | page | int | query | 否 | 頁碼，預設1 | | page_size | int | query | 否 | 每頁數量，預設20 | | status | string | query | 否 | 訂單狀態 |

請求示例

GET /api/v1/orders?page=1&page_size=10&status=paid

響應示例

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 10,
    "list": [
      {
        "id": "ORD202401010001",
        "user_id": 123,
        "amount": 100.00,
        "status": "paid",
        "created_at": "2024-01-01 10:00:00"
      }
    ]
  }
}

介面變更記錄

## 介面設計原則

### RESTful規範
| 方法 | 用途 | 示例 |
|------|------|------|
| GET | 查詢 | GET /users |
| POST | 建立 | POST /users |
| PUT | 完整更新 | PUT /users/1 |
| PATCH | 部分更新 | PATCH /users/1 |
| DELETE | 刪除 | DELETE /users/1 |

### URL命名規範
```markdown
- 使用名詞複數：/users
- 使用小寫：/user-info
- 使用連字元分隔：/order-details
- 避免動詞：不用 /getUser

狀態碼規範

安全建議

• 敏感資訊加密傳輸
• 身份驗證Token過期機制
• 介面呼叫頻率限制
• 引數校驗過濾

這個Skill提供了一套完整的API文件模板，結構清晰、示例詳細，對編寫介面文件很有幫助，適合REST API開發者參考使用。不過內容偏向模板本身，缺乏實戰經驗總結，深度和廣度都有提升空間。對於剛接觸API文件編寫的開發者較為友好，高階開發者可能覺得不夠深入。