Android 與 Java 後端 API 接口文檔編寫規範與範例

文檔結構建議

# 專案名稱 API 文檔 v1.0

## 1. 通用規範
- 協定：HTTPS
- 資料格式：JSON (UTF-8)
- 驗證：Header `Authorization: Bearer `
- 錯誤碼：統一錯誤碼表（附錄）

## 2. 介面清單
| 模組 | 介面 | Method | Path | 說明 |
|------|------|--------|------|------|
| 使用者 | 登入 | POST | /api/v1/auth/login | 帳密登入，回傳 JWT |
| 使用者 | 取得個人資料 | GET | /api/v1/user/profile | 需認證 |

## 3. 介面定義範例
### 3.1 使用者登入
**請求**
POST /api/v1/auth/login
Content-Type: application/json
{
  "username": "string",
  "password": "string",
  "captcha": "string" (optional)
}

**回應成功 (200)**
{
  "code": 0,
  "message": "ok",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600,
    "user": { "id": 1, "name": "張三" }
  }
}

**回應失敗 (400)**
{
  "code": 1001,
  "message": "帳號或密碼錯誤",
  "data": null
}

## 4. 附錄：錯誤碼表
| Code | Message | 說明 |
|------|---------|------|
| 0 | ok | 成功 |
| 1001 | 帳號或密碼錯誤 | 登入失敗 |
| 1002 | Token 過期 | 需重新登入 |

工具推薦

• Swagger/OpenAPI：Spring Boot 整合 springdoc-openapi，自動生成互動式文檔。
• Postman：匯入 OpenAPI 規格，自動生成測試集合。
• Apifox / YApi：國產協作平台，支援 Mock、自動化測試。

關鍵原則

1. 請求/回應欄位全小寫駝峰（userName）。
2. 布林值用 is/has 前綴（isActive）。
3. 時間統一 ISO 8601（2024-01-15T14:30:00Z）。
4. 分頁參數標準化：page, size, sort。

文檔即契約，前後端並行開發的基石，請納入版本控制並持續更新。