- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2.9 KiB
Эндпоинт конвертации
POST /api/v1/convert
Тело запроса — multipart/form-data с обязательным полем file: файл .docx
(OOXML) или .doc (Word 97–2003, переносится мостом в .docx в памяти). Файлы других
расширений отклоняются 400.
Факультативные query/form-параметры
Параметры можно передать в query-строке или как form-поля.
| Параметр | Тип | Дефолт | Действие |
|---|---|---|---|
errorOnCharts |
Boolean | false |
при true диаграммы в документе отменяют конвертацию (422); диаграммы конвертируются в растры всегда |
errorOnSmartArt |
Boolean | false |
при true SmartArt отменяет конвертацию (422) |
errorOnOle |
Boolean | false |
при true OLE-объекты отменяют конвертацию (422); при false OLE-объекты тихо удаляются, картинка-плейсхолдер сохраняется |
maxMb |
число | свойство сервера wordpdf.max-mb (5) |
лимит размера входа в МБ; переопределяет серверный дефолт в обе стороны; ≤ 0 → 400 |
maxPages |
число | свойство сервера wordpdf.max-pages (100) |
лимит числа страниц; переопределяет в обе стороны; ≤ 0 → 400 |
!!! note "На .doc error-флаги не срабатывают"
Плейсхолдеры диаграмм/SmartArt/OLE в бинарном формате — это BLIP-растры, мост
вставляет их картинками; векторные EMF/WMF/PICT пропускаются с warn. Флаги
работают только для .docx.
Успешный ответ
HTTP 200
Content-Type: application/pdf
Content-Disposition: attachment; filename*=UTF-8''Документ.pdf
Имя файла берётся из Content-Disposition загруженного файла, санитизируется
(разрешены буквы, цифры, пробел и ._-; кириллица разрешена; пустое имя → document)
и используется единожды для имени файла, заголовка ответа и заголовка PDF.
Обработка
Задача ставится в однопоточную очередь воркеров (16 мест). Проверка размера —
синхронно до очереди. Конвертация дольше wordpdf.convert-timeout (2m) → 504,
очередь полна → 503. Полная таблица ответов — Коды ошибок,
пороги — Лимиты.