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,74 @@
|
||||
# Примеры клиентов
|
||||
|
||||
Базовый адрес зависит от стенда: прод `https://pjandro.ru/pdf-converter/api/v1/convert`,
|
||||
prod-like локально `http://localhost:9010/api/v1/convert`, dev `http://<LAN-IP>:9011/api/v1/convert`,
|
||||
`java -jar` — `http://localhost:8080/api/v1/convert`.
|
||||
|
||||
## curl
|
||||
|
||||
Без ключа (сервер с выключенной аутентификацией):
|
||||
|
||||
```bash
|
||||
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||
```
|
||||
|
||||
С ключом и error-флагом:
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: $WORDPDF_API_KEY" \
|
||||
-F "file=@Отчёт.docx" \
|
||||
"https://pjandro.ru/pdf-converter/api/v1/convert?errorOnOle=true&maxMb=10" \
|
||||
-o out.pdf
|
||||
```
|
||||
|
||||
## JavaScript (fetch)
|
||||
|
||||
```js
|
||||
const form = new FormData();
|
||||
form.append("file", fileInput.files[0], fileInput.files[0].name);
|
||||
|
||||
const resp = await fetch("/api/v1/convert", {
|
||||
method: "POST",
|
||||
headers: apiKey ? { "X-API-Key": apiKey } : {},
|
||||
body: form,
|
||||
});
|
||||
|
||||
if (!resp.ok) {
|
||||
const { error } = await resp.json().catch(() => ({ error: resp.statusText }));
|
||||
throw new Error(error);
|
||||
}
|
||||
|
||||
// имя файла из Content-Disposition: attachment; filename*=UTF-8''%D0%9E%D1%82%D1%87%D1%91%D1%82.pdf
|
||||
const cd = resp.headers.get("Content-Disposition") ?? "";
|
||||
const m = cd.match(/filename\*=UTF-8''([^;]+)/i);
|
||||
const name = m ? decodeURIComponent(m[1]) : "document.pdf";
|
||||
|
||||
const blobUrl = URL.createObjectURL(await resp.blob());
|
||||
const a = Object.assign(document.createElement("a"), { href: blobUrl, download: name });
|
||||
a.click();
|
||||
URL.revokeObjectURL(blobUrl);
|
||||
```
|
||||
|
||||
Обработка 401 — стереть сохранённый ключ и показать экран ввода; 422 — показать
|
||||
`error` из тела (документ содержит диаграммы/SmartArt/OLE).
|
||||
|
||||
## Python (requests)
|
||||
|
||||
Таймаут обязан быть больше серверных 2 минут на чтение:
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
resp = requests.post(
|
||||
"https://pjandro.ru/pdf-converter/api/v1/convert",
|
||||
headers={"X-API-Key": API_KEY} if API_KEY else {},
|
||||
files={"file": open("doc.docx", "rb")},
|
||||
params={"errorOnCharts": "false"},
|
||||
timeout=(10, 180), # connect 10 c, read 180 c — больше серверных 2m
|
||||
)
|
||||
resp.raise_for_status()
|
||||
with open("doc.pdf", "wb") as f:
|
||||
f.write(resp.content)
|
||||
```
|
||||
|
||||
Так же устроены прод-автотесты репозитория (`prod-autotests/`, pytest + requests).
|
||||
Reference in New Issue
Block a user