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:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+53
View File
@@ -0,0 +1,53 @@
# 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. Проверка размера входа
выполняется синхронно, до постановки в очередь.