API 文件用嘴巴講、用 Word 寫、用 Slack 傳——然後前端照著做完發現跟實際 API 對不上。Swagger 的存在就是為了終結這種悲劇。
先講結論
Swagger（現在叫 OpenAPI）是 API 文件的業界標準。它不只是文件——它是可以互動的文件，前端可以直接在上面測 API、看 response 格式、甚至自動產生 client code。如果你的團隊還在用 Google Sheet 記 API 格式，是時候升級了。
Swagger 到底是什麼
2016 年之後，規範部分改名為 OpenAPI Specification (OAS)，Swagger 變成工具的品牌名稱。但大家還是習慣叫 Swagger，你懂就好。
整個生態系長這樣：
- OpenAPI Spec：用 YAML/JSON 描述你的 API 長什麼樣
- Swagger UI：把 spec 渲染成漂亮的互動式文件
- Swagger Editor：線上編輯 spec
- Swagger Codegen：從 spec 自動產生前端 / 後端程式碼
一份 OpenAPI Spec 長怎樣
openapi: 3.0.0
info:
title: 使用者 API
version: 1.0.0
paths:
/users:
get:
summary: 取得使用者列表
parameters:
- name: page
in: query
schema:
type: integer
default: 1
responses:
'200':
description: 成功
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
/users/{id}:
get:
summary: 取得單一使用者
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: 成功
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
description: 找不到使用者
components:
schemas:
User:
type: object
required: [email, name]
properties:
id:
type: integer
example: 1
name:
type: string
example: "John Doe"
email:
type: string
format: email
role:
type: string
enum: [admin, user, guest]
default: user看起來有點長，但它把你以前用 Word 寫的那些「欄位名稱、型別、必填、範例」全部結構化了。而且這份 YAML 就是你的文件——Swagger UI 會自動渲染成可互動的頁面。
Express.js 整合
用 swagger-jsdoc 讓你直接在 code 旁邊寫文件，而不是另外維護一份 YAML：
npm install swagger-jsdoc swagger-ui-express// swagger.js
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';
const specs = swaggerJsdoc({
definition: {
openapi: '3.0.0',
info: { title: 'My API', version: '1.0.0' },
},
apis: ['./routes/*.js'], // 讀取 JSDoc 註解
});
export function setupSwagger(app) {
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
}// routes/users.js
/**
* @swagger
* /api/users:
* get:
* summary: 取得使用者列表
* tags: [Users]
* responses:
* 200:
* description: 成功
*/
router.get('/', async (req, res) => {
const users = await User.findAll();
res.json(users);
});文件跟 code 放在一起，code 改了文件也跟著改。而不是像以前那樣 code 改了半年，文件還停在上古版本。
最佳實踐
先寫 Spec 再實作（API First Design）——先跟前端對好 API 格式，確認 response 結構，再開始寫 code。這樣前後端可以同時開發，不用等來等去。
用 $ref 重用定義——同一個 User schema 可能出現在十個 endpoint，用 $ref: '#/components/schemas/User' 指過去就好，改一處全部更新。
提供 example——前端看到 type: string 不知道裡面會是什麼，看到 example: "john@example.com" 就清楚了。
完整的錯誤描述——不要只寫 200 的 response。400、401、404、500 都要寫清楚，前端才知道怎麼處理 error。
整合 CI/CD——讓文件自動產生、自動部署。手動維護的文件遲早會跟現實脫節。
好的 API 文件不是「有就好」——是要讓前端看完就能串接，不需要再問你任何問題。