CFDivePlatform/openspec/changes/archive/2026-05-25-swagger-api-docs-completion/design.md at 0814a3196fdb2020d695d5029a6ee6205ed19e19

a620906209/CFDivePlatform

Files

T

a620906209 05ef8b9316 docs:補全所有 API 端點 Swagger 文件（73 個端點）

- 修正 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>

2026-05-25 01:17:25 +08:00

3.2 KiB

Raw Blame History

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

依序建立 5 個新 Doc 檔案
在容器內執行 php artisan l5-swagger:generate
開啟 http://localhost:8080/api/documentation 確認 UI 正確渲染
確認所有 tag 與端點均出現在 Swagger UI

Rollback：直接刪除新增的 Doc 檔案，重新 generate 即可回復到只有 Auth 端點的狀態

3.2 KiB Raw Blame History Unescape Escape