a620906209
0dda2bb2a3
- 修正 AuthApiDoc.php 路徑錯位（/register/member → /member/register 等） 及 change-password 方法（Post→Put）；補上 POST /logout、GET /user - 新增 AuthSupplementDoc.php（Google OAuth 2 端點） - 新增 PublicApiDoc.php（共用 Schema + 公開課程 4 端點） - 新增 MemberApiDoc.php（預約、評價、通知共 13 端點） - 新增 ProviderApiDoc.php（課程、圖片、時段、預約管理共 18 端點） - 新增 AdminApiDoc.php（統計、會員/教練/課程管理共 16 端點） - 更新 README.md - 歸檔 swagger-api-docs-completion change，同步主規格 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
64 lines
3.2 KiB
Markdown
64 lines
3.2 KiB
Markdown
## Context
|
||
|
||
現有 `app/Docs/AuthApiDoc.php` 已建立 Swagger 基礎設定（`@OA\Info`、`@OA\Server`、`@OA\SecurityScheme`）並文件化 15 個 Auth 端點。其餘 61 個端點分散在 8 個 Controller 中，沒有任何 `@OA` 標注。`darkaonline/l5-swagger` 已安裝，執行 `php artisan l5-swagger:generate` 即可重新產生 JSON。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 補齊所有 61 個未文件化端點的 `@OA` 標注
|
||
- 定義共用 Schema（分頁 meta、統一錯誤格式、DivingOffer、Review、Booking 等）
|
||
- 文件依模組分檔，每個新檔對應一個 `app/Docs/*Doc.php`
|
||
- 每個端點包含：summary、parameters、request body（POST/PUT）、response（200/201/400/401/403/422）
|
||
|
||
**Non-Goals:**
|
||
- 不修改任何 Controller / Route / Model 邏輯
|
||
- 不為尚未實作的端點（金流、訂閱）補文件
|
||
|
||
## Decisions
|
||
|
||
### 決策 1：分檔策略 — 依模組建立獨立 Doc 類別
|
||
|
||
**選擇**：每個模組一個 `app/Docs/*Doc.php`
|
||
|
||
| 檔案 | 涵蓋端點 |
|
||
|------|---------|
|
||
| `AuthApiDoc.php` | **修正路徑錯誤**（`/register/member` → `/member/register` 等）；補 `POST /logout`、`GET /user` |
|
||
| `PublicApiDoc.php` | 公開端點（diving-offers、reviews、schedules） |
|
||
| `MemberApiDoc.php` | Member bookings、reviews、helpful、notifications |
|
||
| `ProviderApiDoc.php` | Provider offers、images、schedules、bookings |
|
||
| `AdminApiDoc.php` | Admin stats、users、offers、bookings、reviews |
|
||
| `AuthSupplementDoc.php` | **僅** Google OAuth 2 個端點（`SocialAuthController`） |
|
||
|
||
**理由**：單一大檔難以維護；按模組分檔讓每個 Doc 類別職責清晰，對應 Controller 結構
|
||
|
||
**替代方案**：直接在 Controller 方法上加 `@OA` → 拒絕，Controller 文件與業務邏輯混雜，讀性差
|
||
|
||
### 決策 2：共用 Schema 集中定義在 `PublicApiDoc.php`
|
||
|
||
共用 Schema（`DivingOfferSchema`、`ReviewSchema`、`BookingSchema`、`PaginationMeta`、`ApiErrorResponse`）集中放在 `PublicApiDoc.php` 頂層 `@OA\Schema` 標注。
|
||
|
||
**理由**：l5-swagger 掃描所有 `app/` 目錄，Schema 定義位置不影響其他檔案引用；放在 Public 層語意上最自然（核心資料結構）
|
||
|
||
### 決策 3：Security 標注策略
|
||
|
||
- 公開端點：不加 `security`
|
||
- Member 端點：`security={{"bearerAuth": {}}}`（現有 scheme）
|
||
- Provider 端點：`security={{"bearerAuth": {}}}`
|
||
- Admin 端點：`security={{"bearerAuth": {}}}`
|
||
|
||
三個 role 共用同一個 `bearerAuth` scheme，由後端 middleware 區分角色，不需要在 Swagger 定義三個不同 scheme。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- **[Risk] 手寫標注與實際 response 不同步** → 以實際 Controller 程式碼為準手寫；未來有 API 變更時需同步更新 Doc 檔
|
||
- **[Risk] Schema 巢狀複雜導致 Swagger UI 渲染慢** → 分頁 response 使用 `allOf` 組合，避免深層巢狀
|
||
|
||
## Migration Plan
|
||
|
||
1. 依序建立 5 個新 Doc 檔案
|
||
2. 在容器內執行 `php artisan l5-swagger:generate`
|
||
3. 開啟 `http://localhost:8080/api/documentation` 確認 UI 正確渲染
|
||
4. 確認所有 tag 與端點均出現在 Swagger UI
|
||
|
||
**Rollback**：直接刪除新增的 Doc 檔案，重新 generate 即可回復到只有 Auth 端點的狀態
|