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

Made-with: Cursor

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
+}