快速开始

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,
))