API 文件
規則
- 以 OpenAPI 3.1 規格作為單一事實來源 — 從程式碼生成,而非手動撰寫
- Zod 架構轉換為 OpenAPI:使用
zod-openapi 或 @asteasolutions/zod-to-openapi — 一次定義,同時驗證與文件化
- 互動式文件:Scalar(現代、快速)或 Swagger UI — 在
/docs 或 /api-docs 路徑提供服務
- 每個端點都必須包含:摘要、說明、請求主體架構、所有回應碼及對應範例
- 每個端點都要有範例請求/回應 — 使用貼近真實的資料,避免使用
"string" 這類佔位符
- 版本管理策略:破壞性變更使用 URL 路徑(
/api/v1/、/api/v2/) — 比標頭版本管理更簡單
- 錯誤回應:統一文件化所有錯誤形狀 —
{ error: string, code: string, details?: object }
- 認證機制:在安全方案區段中文件化認證機制(Bearer Token、API Key)
- 按資源分組端點:
/users、/products、/orders — 在文件 UI 中使用標籤(tags)進行分組
範例
import { z } from "zod";
import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
extendZodWithOpenApi(z);
const UserSchema = z.object({
id: z.string().uuid().openapi({ example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }),
name: z.string().openapi({ example: "Jane Smith" }),
email: z.string().email().openapi({ example: "[email protected]" }),
}).openapi("User");
const CreateUserSchema = UserSchema.omit({ id: true }).openapi("CreateUser");
registry.registerPath({
method: "post",
path: "/api/v1/users",
summary: "建立使用者",
request: { body: { content: { "application/json": { schema: CreateUserSchema } } } },
responses: {
201: { description: "使用者建立成功", content: { "application/json": { schema: UserSchema } } },
400: { description: "驗證錯誤" },
},
});
避免事項
- 手動撰寫 OpenAPI YAML — 應從 Zod 架構或路由定義生成
- 遺漏錯誤回應的文件化 — 務必文件化 400、401、403、404、500 狀態碼
- 使用通用範例如
"string" 或 0 — 應使用能展現真實資料形狀的實際值
- 文件與實作脫節 — 應從驗證用的相同架構生成規格