b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
54 lines
2.7 KiB
Markdown
54 lines
2.7 KiB
Markdown
# REST API
|
|
|
|
Базовый путь — корень сервера; единственный эндпоинт:
|
|
|
|
```
|
|
POST /api/v1/convert
|
|
```
|
|
|
|
Quickstart — конвертировать документ и сохранить PDF (ключ доступа, если сервер его
|
|
требует, — в заголовке `X-API-Key`):
|
|
|
|
```bash
|
|
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
|
|
https://pjandro.ru/pdf-converter/api/v1/convert -o doc.pdf
|
|
```
|
|
|
|
Локальный бэкенд (`java -jar`, порт 8080, ключ выключен):
|
|
|
|
```bash
|
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
|
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
|
```
|
|
|
|
Успешный ответ — `200`, тело — байты PDF (`Content-Type: application/pdf`,
|
|
`Content-Disposition: attachment; filename*=UTF-8''…`).
|
|
|
|
## Документация в самом сервисе
|
|
|
|
|Что|Путь|Когда доступно|
|
|
|---|---|---|
|
|
|Swagger UI|`/swagger-ui.html`|пока включён springdoc|
|
|
|OpenAPI (JSON)|`/v3/api-docs`|пока включён springdoc|
|
|
|
|
На `java -jar` и dev-стенде (:9011) springdoc включён; на проде он также открыт
|
|
(проверяется автотестом `test_swagger_ui_open_without_key`). В локальном prod-like
|
|
compose-стеке springdoc выключен env-ами `SPRINGDOC_API_DOCS_ENABLED=false` и
|
|
`SPRINGDOC_SWAGGER_UI_ENABLED=false` (в этом случае `/v3/api-docs` отвечает 404).
|
|
|
|
## Разделы
|
|
|
|
- [Аутентификация](authentication.md) — ключ `X-API-Key`.
|
|
- [Эндпоинт конвертации](convert-endpoint.md) — параметры и ответ.
|
|
- [Коды ошибок](errors.md) — полная таблица и тексты.
|
|
- [Лимиты](limits.md) — размер, страницы, очередь, таймаут.
|
|
- [Примеры клиентов](examples.md) — curl, JavaScript, Python.
|
|
|
|
## Как устроена обработка
|
|
|
|
Конвертации сериализуются **одним воркером**: ядро мутирует глобальный реестр шрифтов,
|
|
поэтому все конвертации идут последовательно (очередь — 16 мест, переполнение → 503).
|
|
Головой очереди на старте стоит `warmup()` — прогрев ядра (~1,5–2,5 с), чтобы первый
|
|
запрос после деплоя не платил за инициализацию JAXB/XSLT/FOP. Проверка размера входа
|
|
выполняется синхронно, до постановки в очередь.
|