docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
@@ -0,0 +1,45 @@
|
||||
# Эндпоинт конвертации
|
||||
|
||||
```
|
||||
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. Полная таблица ответов — [Коды ошибок](errors.md),
|
||||
пороги — [Лимиты](limits.md).
|
||||
Reference in New Issue
Block a user