如何在 Confluence 中記錄 API

API 文檔總是因相同的原因失敗：它們存放在太多地方，沒有人擁有它們，而且更新它們感覺是可選的。

The Postman 收集套裝是真正的參考。Swagger 檔案落後於程式碼六個月。Confluence 頁面曾經準確過。README 有個 curl 範例在 v2 中停止運作。新來的開發者必須在這些東西之間進行三角測量，並且還要問同事。

將 API 文件在 Confluence 中集中起來，並不能自動解決所有這些問題 — 但它為你提供了一個可以從任何地方連結的位置，而正確的結構讓你遠比以往更容易保持更新.

API 文件為何會變得過時

核心問題並非人們懶惰。問題在於文件記錄與程式碼存放於不同工具中，因此每次變更都需要兩個動作：更新程式碼，接著更新文件。當截止日期緊迫時，這第二步驟就會被省略，而且文件總是無法趕上變更的速度。

次要問題層層堆疊：

沒有明確的負責人。 建立這個程式碼的開發者離開了。沒有人足夠了解它，以確信進行更新。
格式錯誤. 請求體的散文式描述含糊不清。沒有解釋的代碼示例假設太多。沒有統一結構的兩者混合是最糟糕的.
作為唯一來源 Swagger/OpenAPI. 自動生成的文件顯示了 API 的功能，而不是為什麼，有哪些陷阱，或者邊緣情況下實際生產行為的樣子。

優質的 API 文件應該結合自動生成的規範輸出與手寫的上下文。手寫的上下文應該放在 Confluence 上.

優質 API 文件的內容

對於每個 API（或邏輯端點群組），您的文件應該涵蓋：

身份驗證和授權 — 如何獲取憑證、令牌存活時間、範圍需求，哪些終點需要哪些權限。這是最常被新整合者詢問的問題，也是最難在自動生成的文件中找到的內容。

基礎 URL 和版本控制 — 當前版本、版本控制如何運作、淘汰政策。一個顯示 v1/v2 差異的表格比一段話更有價值。

終點參考 — 對於每個終端點：方法、路徑、描述、請求參數（路徑、查詢、標頭、主體）、範例請求、範例回應、錯誤代碼。請參考本帖底部的模板.

錯誤代碼 — 一個專用的錯誤代碼表格，說明它們的含義以及調用者應該如何處理它們。400 Bad Request 不是有用的文件.

變更記錄 — 哪些版本之間變更了？變更是什麼時候發生的。變更日誌是現有整合者當發布後某個功能出現問題時首先檢查的東西.

速率限制和配額 — 數字，什麼觸發速率限制，響應看起來像什麼，如何處理重試.

在Confluence中結構化API文件

一個適合團隊維護一個或多個 API 的 Confluence 空間結構：

API Documentation (space root)
├── Getting Started
│   ├── Authentication
│   ├── Rate Limits & Quotas
│   └── SDKs & Client Libraries
├── API Reference
│   ├── Users API
│   │   ├── GET /users
│   │   ├── POST /users
│   │   ├── GET /users/{id}
│   │   └── DELETE /users/{id}
│   └── Orders API
│       └── ...
├── Changelog
│   ├── v3.0.0 (2026-04-01)
│   ├── v2.5.0 (2025-12-10)
│   └── ...
└── Guides
    ├── Handling Pagination
    ├── Webhook Setup
    └── Error Handling Patterns

在每個 API 組中保持 API 參考部分平坦 — 每個端點一頁。過於嵌套會讓側邊欄無用。Changelog 和 Guides 結構是您撰寫散文的地方；參考結構是您撰寫規格的地方。

在 Confluence 中撰寫請求和回應範例

這裡是大多數 Confluence API 文檔失敗的地方。人們撰寫 JSON 字段的散文描述，或者貼上無法掃描的非格式化請求範例。

正確的方法是使用清晰標籤的結構化代碼塊。 Confluence 的 Markdown 渲染器允許您直接在任何 Confluence 頁面上以 markdown 格式編寫 — 包括帶有語言提示的鎖定代碼塊，這些代碼塊會以語法高亮的方式呈現。

在 Confluence 頁面上以 markdown 格式編寫的請求範例：

**Request**

http
POST /v3/orders
Authorization: Bearer {token}
Content-Type: application/json

{
"customer_id": "cus_8f3k2",
"items": [
{ "sku": "WIDGET-001", "quantity": 2 },
{ "sku": "GADGET-042", "quantity": 1 }
],
"shipping_address": {
"line1": "123 Main St",
"city": "Austin",
"state": "TX",
"zip": "78701"
}
}
`

回應 — 201 已建立

json { "order_id": "ord_9g4m1", "status": "pending", "created_at": "2026-05-20T14:32:00Z", "total_cents": 4799 } ``


This renders cleanly in Confluence via Markdown Renderer, and it's easy to edit. No Confluence macro hunting, no storage format XML — just write markdown.

---

## Keeping Docs in Sync with Code

The documentation drift problem doesn't go away with better structure — it needs a process fix too.

**Link the Confluence page from the code.** Add a comment in the route handler or controller pointing to the Confluence page. When a developer changes the endpoint, the link is right there.

python

POST /v3/orders

文檔： https://yourspace.atlassian.net/wiki/x/AbCdEf

@app.route("/v3/orders", methods=["POST"])
def create_order():
...


**Add the docs update to your PR checklist.** If your team uses a PR template, add a checkbox: "Updated API docs in Confluence if endpoints changed." It sounds obvious but it works.

**Use the Confluence REST API for automated updates.** For teams with documentation-as-code workflows, the Confluence REST API lets you push page updates from CI. Your OpenAPI spec can be auto-rendered into a Confluence page on every merge to main, and the hand-written context pages stay separate and stable.

bash

透過 REST API 更新 Confluence 頁面

curl -X PUT \
"https://yoursite.atlassian.net/wiki/rest/api/content/{pageId}" \
-H "Authorization: Bearer $CONFLUENCE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"version": { "number": 12 },
"title": "GET /users/{id}",
"type": "page",
"body": {
"storage": {
"value": "

更新內容在此

__,
"representation": "storage"
}
}
}'


---

## Page Template: API Endpoint Reference

Here's a practical template for a single endpoint page. Copy it, fill it in, repeat per endpoint.

markdown

概覽

簡要說明此終點點的作用以及何時使用它。

請求

方法 & 路徑: POST /v3/users

認證: 需要帶有權杖的 token。範圍: users:write

標頭

標頭	必需	描述
`Authorization`	是	`Bearer {token}`
`Content-Type`	是	`application/json`

內容參數

欄位	類型	必填	描述
`email`	字串	是	用戶的電子郵件地址
`name`	字串	是	顯示名稱
`role`	字串	否	其中之一: `admin`, `member`, `viewer`。預設值:`member`

示例請求

POST /v3/users
Authorization: Bearer eyJhb...
Content-Type: application/json

{
  "email": "alex@example.com",
  "name": "Alex Kim",
  "role": "member"
}
` ``

## Response

### 201 Created

json
{
"user_id": "usr_7c2p9",
"email": "alex@example.com",
"name": "Alex Kim",
"role": "成員",
"created_at": "2026-05-20T10:00:00Z"
}
`

錯誤代碼

代碼	意義	操作
`400`	缺少必填欄位	檢查請求體對應模式
`409`	郵箱已註冊	使用現有賬號或更改郵箱
`422`	無效的角色值	使用其中之一：admin, member, viewer
`429`	速率限制超出	暫停後再嘗試`Retry-After` 標頭

註記

有任何陷阱、速率限制的特定細節，或行為與一般規則不同
`

開始使用

安裝Confluence Markdown Renderer 由 Atlassian Marketplace 提供，可在 Confluence 頁面上直接使用 Markdown 寫和編輯 API 文檔 — 代码塊、表格等全部支持.

有問題嗎？透過我們的支援入口聯繫我們.

推薦訂閱源

DEV Community