mirror of
https://github.com/Vateron-Media/XC_VM.git
synced 2026-10-05 04:02:31 +02:00
Divarion_D
dcd1d8c860
Replace the hand-maintained Docsify site (parallel docs/en + docs/ru trees that had already drifted) with a MkDocs Material build where English is the single source of truth and Russian is generated at build time. Engine & structure - mkdocs.yml: Material theme, site_url for the /XC_VM/ Pages subpath, and a two-tab information architecture — User Guide (administration, API/Swagger, UI translations, diagnostics, info/FAQ) vs Developer Guide (architecture, workflow, security, integrations, build). Files are NOT moved — the split is nav-only, so URLs and cross-links stay stable. - mkdocs-static-i18n (folder mode): English at root, Russian under /ru/, with a language switcher. `mkdocs build --strict` validates every link/anchor. Translation pipeline (tools/docs/translate.py) - Engine-agnostic via DOCS_TRANSLATE_PROVIDER: translators (free, no API key — default), anthropic, deepl, or noop. Per-file sha256 cache so only changed English files are re-translated. Markdown-safe: code, URLs, HTML tags and glossary terms (XC_VM, FFmpeg, HLS, ...) are masked and never translated. A file whose translation fails falls back to English so the build never breaks. - docs/ru is generated and gitignored — never committed. It is produced locally (`make docs-serve` / `docs-build`) and in CI. CI & tooling - pages.yml: build-then-upload (setup-python -> install -> restore .docs-cache with restore-keys -> translate -> mkdocs build --strict -> deploy), replacing the verbatim docs/ upload. - Makefile: docs-venv / docs-translate / docs-build / docs-serve. - docs/requirements.txt; .gitignore for docs/ru, site/, .docs-cache. Migration details - Removed Docsify control files (index.html, _navbar.md, _sidebar.md, .nojekyll) and de-Docsify-ed body links in 6 English files (en-us/ aliases -> relative, swagger _media paths, stripped ':ignore' link syntax). - Preserved the two Russian-only planning docs (no English source) by moving them into docs/adr/ as *.ru.md (repo-internal, excluded from the site).
32 lines
2.0 KiB
Markdown
32 lines
2.0 KiB
Markdown
# Interactive API Reference (Swagger)
|
|
|
|
Interactive, always-in-sync Swagger UI for every XC_VM API, generated from OpenAPI 3.0 specifications. Use the **API tabs** at the top of the page to switch between APIs, or open one directly via the links below.
|
|
|
|
| API | Description | Auth | Open |
|
|
| --- | --- | --- | --- |
|
|
| **Admin API** | XUI.ONE-compatible administration — lines, users, streams, VOD, series, servers, settings (104 endpoints) | `api_key` + access code | [Open ↗](../../_media/swagger-ui.html?spec=admin) |
|
|
| **System API** | Internal `/api.php` — stream/VOD control, stats, processes, files, connections (31 actions) | `password` (`live_streaming_pass`) | [Open ↗](../../_media/swagger-ui.html?spec=system) |
|
|
| **Player API** | XtreamCodes player — Live TV, VOD, Series, EPG | `username` + `password` | [Open ↗](../../_media/swagger-ui.html?spec=player) |
|
|
| **Playlist API** | `/playlist` authentication + playlist generation | `username`/`password` or `token` | [Open ↗](../../_media/swagger-ui.html?spec=playlist) |
|
|
|
|
---
|
|
|
|
## Using "Try it out"
|
|
|
|
1. Open a spec, then use the **API tabs** to switch APIs, and the **Documentation / Interactive (Swagger)** tabs for each API.
|
|
2. Expand any endpoint → **Try it out** → fill parameters → **Execute** to see the real request URL, cURL command and live response.
|
|
3. For the Admin API, click **Authorize 🔓** and paste your API key — it is then attached to every request automatically.
|
|
|
|
> **CORS note:** direct "Try it out" calls from the browser to your server may be blocked by CORS. This is expected — use the generated cURL command, Postman or Insomnia instead. The error does not mean the API is broken.
|
|
|
|
---
|
|
|
|
## Raw specifications
|
|
|
|
Every spec can be imported into Postman, Insomnia or any OpenAPI 3.0 tooling:
|
|
|
|
- [`admin-api.openapi.yaml`](../../_media/admin-api.openapi.yaml)
|
|
- [`system-api.openapi.yaml`](../../_media/system-api.openapi.yaml)
|
|
- [`player-api.openapi.yaml`](../../_media/player-api.openapi.yaml)
|
|
- [`playlist-api.openapi.yaml`](../../_media/playlist-api.openapi.yaml)
|