docs: openapi.html со встроенным Redoc; инструкция для Gitea и скрипт сборки

Made-with: Cursor

docs/OPENAPI-GITEA.md

@@ -0,0 +1,34 @@
+# Как смотреть API-документацию (Gitea без встроенного OpenAPI)
+
+В веб-интерфейсе Gitea файлы из репозитория показываются **как исходный текст** (в т.ч. HTML) — это нормально: страница в браузере **не выполняется** из просмотра кода.
+
+## Самый простой способ
+
+1. Откройте в репозитории файл **`docs/openapi.html`**.
+2. Нажмите **Скачать** (или откройте ссылку **Raw** и сохраните файл как `openapi.html`).
+3. Откройте сохранённый файл **двойным щелчком** в браузере.
+
+В `openapi.html` уже **встроен** движок Redoc (отдельный интернет для скрипта не нужен).
+
+## Если хотите открывать по ссылке Raw в браузере
+
+Нужно, чтобы Gitea отдавал HTML с типом `text/html`, а не `text/plain`. Администратор может добавить в **`app.ini`**:
+
+```ini
+[download.mimetype.mapping]
+.html=text/html
+```
+
+После перезапуска Gitea ссылка **Raw** на `docs/openapi.html` может открываться как обычная страница (зависит от версии и политики `nosniff`).
+
+## Пересборка после правок `openapi.yaml`
+
+Из корня репозитория:
+
+```powershell
+.\scripts\build-openapi-html.ps1
+```
+
+Или вручную: `npx @redocly/cli@1 build-docs docs/openapi.yaml -o docs/openapi.html`, затем встроить `redoc.standalone.js` по аналогии со скриптом.
+
+Источник правды по контракту API — **`docs/openapi.yaml`** (OpenAPI 3.1).

scripts/build-openapi-html.ps1

@@ -0,0 +1,22 @@
+# Пересборка docs/openapi.html: Redoc вшит внутрь (один файл — удобно скачать и открыть в браузере).
+$ErrorActionPreference = "Stop"
+$root = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
+Set-Location $root
+if (-not (Test-Path "docs/openapi.yaml")) { throw "Run from repo root (docs/openapi.yaml missing)" }
+
+$redocUrl = "https://cdn.redocly.com/redoc/v2.5.0/bundles/redoc.standalone.js"
+$tmpJs = Join-Path $env:TEMP "redoc-standalone-$(Get-Random).js"
+try {
+    Invoke-WebRequest -Uri $redocUrl -OutFile $tmpJs -UseBasicParsing
+    npx --yes @redocly/cli@1 build-docs docs/openapi.yaml -o docs/openapi.html
+    $html = [System.IO.File]::ReadAllText("$root/docs/openapi.html", [System.Text.UTF8Encoding]::new($false))
+    $js = [System.IO.File]::ReadAllText($tmpJs, [System.Text.UTF8Encoding]::new($false))
+    $needle = '<script src="https://cdn.redocly.com/redoc/v2.5.0/bundles/redoc.standalone.js"></script>'
+    if (-not $html.Contains($needle)) { throw "Unexpected openapi.html: CDN script tag not found" }
+    $html2 = $html.Replace($needle, "<script>`r`n" + $js + "`r`n</script>")
+    [System.IO.File]::WriteAllText("$root/docs/openapi.html", $html2, [System.Text.UTF8Encoding]::new($false))
+    Write-Host "OK: docs/openapi.html ($( [math]::Round((Get-Item docs/openapi.html).Length / 1MB, 2) ) MiB)"
+}
+finally {
+    Remove-Item -Force -ErrorAction SilentlyContinue $tmpJs
+}