API Spec · OpenAPI 契約 · 落地圖鑑

CHOOSE YOUR MODE

先決定你現在是要學，還是要在專案裡做

網站負責解釋與分發工作包；真正的 Repository 掃描、缺口判斷與文件產出交給 Coding Agent。

SDLC 實作課 · 交付物練習

先理解這份文件替你消除什麼不確定

Freeze 契約，讓 FE/BE/QA 可平行開發

FE 跟 BE 並行開發，整合那一刻才發現欄位名不同、型別不同、error code 不一致。一週都在補洞。

API Spec（OpenAPI 3.1）的核心價值是讓契約先穩定，雙方可以從 mock server 開始平行寫 code、寫 test。

沒 freeze 契約就動工，等同沒對齊就一起跑步。

OWNER & HANDOFF

誰負責、交給誰

主責： Architect / Dev Lead（決定契約）

協作： FE（消費者驗證）、BE（生產者驗證）、QA（測試對齊）

下游收件： FE/BE 平行寫 code、QA 寫 contract test、SDK 自動生成

WHEN TO USE

何時值得做

REQUIRED

必要時機： FE/BE 跨團隊、microservice 整合、對外 public API

SKIP

不需要時：內部 monolith 函式呼叫、單一團隊全棧

CAUTION

常見誤用：漏掉 error code / idempotency / rate limit / auth；OpenAPI 3.1 必填 endpoint + schema + auth + error + idempotency，並有 change policy（breaking change 需 review）

看懂6 段骨架知道每段要留下哪一種判斷

看會SmartTrip 案例對照真實素材如何形成結論

做出自己的草稿手動貼到 Claude Code、Codex 或其他 Agent

01讀大綱
02看案例
03填素材
04貼提示詞
05對照驗收

Anatomy · 文件解剖

輕量版先回答 6 個核心章節

章節名稱可以因團隊調整，但每一段要求的判斷不能被省略。先讀問題，再看格式。

01
Executive Summary
範本必要章節
3-5 行說明 API 用途、主要 consumer、freeze 狀態
02
Endpoints（核心 CRUD）
範本必要章節
輕量版列 3-5 個核心 endpoint。Idempotency 在 POST/PATCH 必標
03
Request / Response Schemas
範本必要章節
每個 endpoint 至少列出 required fields + 型別 + 主要 validation
05
Error Taxonomy（核心）
範本必要章節
至少列出本 spec 涉及的 5-8 個 error code
10
Decision Log
範本必要章節
每條必含 chosen + 至少 1 個 rejected option + 拒絕原因
12
Confidence & Sources & TODO
範本必要章節
把已確認的內容、判斷依據與仍待補充的資訊清楚分開。

Study · 對照學習

同一份交付物，先練核心，再看完整深度

輕量範本適合第一次練習與 MVP；完整範本保留跨職能交棒需要的細節。兩者都要求未知事項保持可見。

LIGHT TEMPLATE

30 分鐘內先完成核心章節。

---
doc_type: "api-spec"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["srs", "user-story"]
  optional: ["api-style-guide", "error-taxonomy"]
---

# API Spec: <api-name> v0.X

**Status:** Draft · **Owner:** <Architect/BE Lead> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 6 段（編號 1, 2, 3, 5, 10, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每結論行內加 `（依據：srs §XXX）`；每欄位帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造欄位或 error code；endpoint 涵蓋 happy path 即可，但 error response 至少含 400/401/500 三類。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行說明 API 用途、主要 consumer、freeze 狀態 -->

<3-5 行說明>

> **TL;DR:** <一句話：本 API 服務什麼業務動作>

---

## 2. Endpoints（核心 CRUD）

<!-- ai-rule: 輕量版列 3-5 個核心 endpoint。Idempotency 在 POST/PATCH 必標 -->

| Method | Path | Operation | Auth | Idempotency | Confidence |
|---|---|---|---|---|---|
| POST | `/v1/<resource>` | createX | `<resource>:write` | required | **[H]** |
| GET | `/v1/<resource>/{id}` | getX | `<resource>:read` | n/a | **[H]** |
| PATCH | `/v1/<resource>/{id}` | updateX | `<resource>:write` | optional | **[M]** |

---

## 3. Request / Response Schemas

<!-- ai-rule: 每個 endpoint 至少列出 required fields + 型別 + 主要 validation -->

### `POST /v1/<resource>` · Request

| Field | Type | Required | Validation |
|---|---|---|---|
| `customer_id` | string (uuid) | [YES] | pattern `^[0-9a-f-]{36}$` |
| `items` | array | [YES] | minItems 1, maxItems 100 |

### `POST /v1/<resource>` · Responses

| Status | Schema | Notes |
|---|---|---|
| `201` | `XCreated` | success |
| `400` | `ValidationError` | error codes: `INVALID_CUSTOMER`, `ITEMS_EMPTY` |
| `401` | `AuthError` | missing / invalid token |
| `409` | `IdempotencyConflict` | duplicate Idempotency-Key |
| `500` | `InternalError` | unhandled |

---

## 5. Error Taxonomy（核心）

<!-- ai-rule: 至少列出本 spec 涉及的 5-8 個 error code -->

| Code | HTTP | Retryable | User message key |
|---|---|---|---|
| `INVALID_CUSTOMER` | 400 | [NO] | `error.customer.invalid` |
| `ITEMS_EMPTY` | 400 | [NO] | `error.items.empty` |
| `AUTH_TOKEN_EXPIRED` | 401 | [NO] | `error.auth.expired` |

---

## 10. Decision Log

<!-- ai-rule: 每條必含 chosen + 至少 1 個 rejected option + 拒絕原因 -->

| Date | Decision | Options | Chosen | Rejected why | Confidence |
|---|---|---|---|---|---|
| YYYY-MM-DD | 分頁策略 | cursor / offset | cursor | offset (大資料集 deep page 效能差) | **[H]** |

---

## 12. Confidence & Sources & TODO

- **整份文件最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Fabricated assumptions（推測但 input 未明說）：**
  - <假設 1：例：假設 JWT bearer auth>
- **Highest-value next input:** <下一份最該補的資料>

### TODO（缺資料）

- _TODO: 需要 BE 確認 ratelimit 預設值_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 6 段 H2 章節齊全（編號 1, 2, 3, 5, 10, 12，刻意不連號）
> - [ ] 每個 POST/PATCH endpoint 標 idempotency
> - [ ] Error response 至少含 400/401/500 三類
> - [ ] Decision Log ≥ 1 條，每條有 rejected reason
> - [ ] 無 YAML / JSON schema 直接傾倒（用表格表達 spec 結構）

Practice · 換你試做

先用自己的話交代素材，不需要先學會工程術語

確定的就寫，不確定的留白。下一步要做的是請 Agent 找缺口，不是讓它替你猜一套合理答案。

01這份文件要處理什麼

02目前已知背景

03可以採信的上游素材

04限制與不能自行改的事

05這份文件要幫誰做決定

可以先留白；複製提示詞後再到 Coding Agent 裡補充。

AI Practice · 手動三步

先問、再寫、最後審，不把整條流程鎖死

每一步都是獨立工作包。你可以停下補資料、修改限制或重做某一步，不需要服從固定的 Agent 接力流程。

STEP 01

只找阻擋文件成立的未知

先補會改變範圍、判斷或驗收結果的資訊，不急著寫文件。

我要製作「API Spec · OpenAPI 契約」。先不要產出文件。

請根據我的素材，找出會影響這份文件正確性或可執行性的未知事項，一次最多問 5 題。

每題請包含：
1. 問題
2. 為什麼現在必須知道
3. 它會影響哪個章節或決定

已經回答的事不要重問；可以延後的事標成「待決策」；不要替我猜答案。

本文件的核心章節：Executive Summary、Endpoints（核心 CRUD）、Request / Response Schemas、Error Taxonomy（核心）、Decision Log、Confidence & Sources & TODO

複製後，請在標示位置貼上自己的素材。

Review · 自己驗收

文件存在，不代表下一個角色真的能使用

逐條檢查 Agent 的輸出。人類負責需求、限制與驗收，也必須能說明重要結論從哪裡來。

CHECKED0 / 6

輕量範本要求的章節都存在，沒有用漂亮摘要取代必要內容。每個重要結論都能回到使用者素材、上游文件或已確認回答。資訊不足的地方明確標成 TODO、未知或待決策，沒有讓 AI 自行補完。數字、角色、範圍與條件具體到能被下一位接手者判斷。已做決定與仍可調整的內容分開，限制之間沒有互相矛盾。你能用自己的話說明這份文件最重要的三個判斷與依據。

NEXT HANDOFF

帶著這份文件，繼續到「Data Model · 資料模型」

下一張卡會接住新的決策問題；不用一次把整條 SDLC 全做完。

前往下一張卡