快速開始

DOCX 轉 PDF HTTP API

部署具認證的 FastAPI 私有 DOCX 轉 PDF 服務，搭配 LibreOffice 或 Gotenberg、健康檢查、流量限制與 OpenAPI 3.1 契約。

API 總覽

私有 HTTP adapter 刻意提供精簡的 DOCX 轉 PDF 介面。請使用下表端點執行轉換、診斷與部署健康檢查。

HTTP API 端點
端點	認證	用途
POST /conversions	Bearer token	將上傳的 DOCX 位元組轉換為 PDF
GET /engines	Bearer token	列出已設定 renderer 的能力
GET /live	無	確認程序仍在運行
GET /ready	無	確認預設 renderer 是否就緒
GET /version	無	回傳套件版本

啟動 API

安裝選用的 API 相依套件、設定高強度 API key，並在 8000 port 啟動 application factory。

uv sync --extra api
$env:GORDON_DOC_API_KEY = "replace-me"
uv run uvicorn gordon_doc_converter.api.app:create_app --factory --host 127.0.0.1 --port 8000

轉換文件

POST /conversions 只接受 DOCX request body，並回傳 application/pdf。請在 X-Filename 傳送原始檔名、在 Content-Type 傳送 DOCX 的 OOXML MIME type；設定 API key 時另須 Bearer token。選用的 engine query parameter 接受 libreoffice 或 gotenberg；API 刻意不提供 Word COM。伺服器會將上傳暫存於臨時目錄、驗證 OOXML package 與限制、呼叫設定的惡意程式掃描 hook，並在回應前刪除暫存檔。

curl --fail-with-body \
  -H "Authorization: Bearer replace-me" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  -H "X-Filename: report.docx" \
  --data-binary @report.docx \
  "http://127.0.0.1:8000/conversions?engine=libreoffice" \
  --output report.pdf

互動式 API 文件

文件站會發布產生的 OpenAPI 3.1 契約與內建的唯讀 Swagger UI。你可以在瀏覽器檢視 JSON，或下載後交由程式碼產生與驗證工具使用。

檢視 OpenAPI JSON 下載 OpenAPI JSON 開啟 Swagger UI

可用端點

規格包含文件轉換、引擎探索、存活檢查、就緒檢查與版本端點。受保護的 request 使用 Bearer token。

# Protected: requires Authorization: Bearer <api-key>
POST /conversions?engine=libreoffice|gotenberg
GET  /engines

# Unprotected operational metadata
GET  /live     # {"status": "ok"}
GET  /ready    # 200 ready, 503 not-ready
GET  /version  # {"version": "0.6.0"}

狀態碼與作業限制

成功轉換會以 200 回傳 PDF attachment。無效引擎或輸入回傳 400；缺少或無效憑證回傳 401；來源超過大小限制回傳 413；renderer 失敗回傳 422；速率或並行容量耗盡回傳 429；內部暫存或服務錯誤回傳 500；認證或惡意程式掃描服務不可用回傳 503。/ready 會檢查設定的預設引擎，而非只確認程序仍存活。內建的固定視窗速率限制與並行限制只在單一 process 內有效，因此多副本的正式部署還須在 ingress 或 gateway 提供分散式限制。

設定與整合 Hooks

create_app 可接受 ApiSettings 或使用環境預設值。GORDON_DOC_API_KEY 會啟用預設的常數時間 Bearer-token 比對。GORDON_DOC_GOTENBERG_URL 會設定 Gotenberg adapter，並令其成為預設引擎；否則使用 LibreOffice。ApiSettings 也控制轉換逾時、最大並行轉換數、固定視窗請求速率與輸入限制。整合私有身分、掃描或可觀測性系統時，請提供 auth_hook、malware_scan_hook 與 telemetry_hook。Telemetry 僅接收不含內容的欄位；切勿輸出文件內容、憑證或客戶路徑。

from gordon_doc_converter.api.app import ApiSettings, create_app

app = create_app(settings=ApiSettings(
    api_key='read-from-a-secret-store',
    timeout_seconds=120,
    max_concurrent_conversions=2,
    rate_limit_requests=30,
    rate_limit_window_seconds=60,
))