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).