はじめに

DOCX から PDF への HTTP API

LibreOffice または Gotenberg、ヘルスエンドポイント、各種制限、OpenAPI 3.1 契約を備えた認証付き FastAPI サービスを、プライベートな DOCX から PDF への変換のために配備します。

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 で 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 を受け付けます。Word COM は API では意図的に提供されません。サーバーはアップロードを一時ディレクトリに置き、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 を開く

利用可能なエンドポイント

仕様にはドキュメント変換、エンジン探索、liveness、readiness、バージョンのエンドポイントが含まれます。保護されたリクエストは 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 はプロセスが稼働していることを確認するだけでなく、設定された既定エンジンを検査します。組み込みの固定ウィンドウ方式のレート制限と並行数制限はプロセス単位でのみ有効なため、複数レプリカの本番配備では ingress や gateway でも分散型の制限を適用する必要があります。

設定と統合 Hooks

create_app は ApiSettings または環境変数の既定値を受け付けます。GORDON_DOC_API_KEY は既定の定数時間 Bearer token 比較を有効にします。GORDON_DOC_GOTENBERG_URL は Gotenberg adapter を設定し、Gotenberg を既定エンジンにします。設定しない場合は 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,
))