Однокнопочная сборка и просмотр публичной спеки. Один источник истины — space-platform-api.yaml; bundles/complete-api.yaml теперь лишь симлинк для обратной совместимости.
Образ автоматически собирается при каждом push в main:
# запуск контейнера на порту 3000 с готовым образом из GitHub Container Registry
docker run -p 3000:80 ghcr.io/tkavelli/reezonly-space-openapi:latest
# открыть в браузере
open http://localhost:3000# сборка образа
docker build -t reezonly-space-openapi .
# запуск контейнера на порту 3000
docker run -p 3000:80 reezonly-space-openapi
# открыть в браузере
open http://localhost:3000Доступные эндпоинты:
- UI (Redoc): http://localhost:3000
- YAML (основной): http://localhost:3000/space-platform-api.yaml
- YAML (симлинк): http://localhost:3000/bundles/complete-api.yaml
Если хочешь редактировать спеку и видеть изменения в браузере в реальном времени.
# установить npm пакеты (используется package-lock.json)
npm ci
# установить зависимости для build.js
cd tools && npm ci && cd ..# собирает всё из specs/* в space-platform-api.yaml
npm run bundleЧто происходит:
tools/build.jsчитает все YAML файлы изspecs/(users, groups, certificates, learning, reports)- Объединяет их в один
space-platform-api.yaml - Создаёт симлинк
bundles/complete-api.yaml→space-platform-api.yaml
# собирает спеку и генерирует красивый HTML в docs/index.html
npm run build-docsПроцесс:
npm run bundle— собирает YAMLredocly build-docs— генерирует HTML из YAMLtools/add-try-link.js— добавляет логотип и скрипты
# запуск простого HTTP сервера на порту 3000
python3 -m http.server 3000
# или используй Node.js
npx http-server -p 3000Открой http://localhost:3000/docs/index.html в браузере.
Если часто редактируешь specs/*.yaml:
npm run watchЭто автоматически пересобирает space-platform-api.yaml при любом изменении specs/.
# проверить YAML на ошибки (требования к descriptions, примерам и т.д.)
npm run lint
# или использовать redocly напрямую
redocly lint space-platform-api.yamlПравила линтинга определены в redocly.yaml:
- ✅ Каждый метод должен иметь
description - ✅ Каждый параметр должен иметь
description - ✅
operationIdдолжен начинаться с глагола:get|list|create|update|delete|download|assign - ✅ Все компоненты должны использоваться
- ✅ Все ссылки должны быть валидны
reezonly-space-openapi/
├── package.json # основные зависимости (redocly, nodemon)
├── package-lock.json # фиксированные версии (обязателен для npm ci)
├── .gitignore # исключает node_modules из гита
│
├── redocly.yaml # конфиг Redocly (theme, rules, lint)
├── space-platform-api.yaml # собранный OpenAPI (итоговый файл)
│
├── specs/ # исходные YAML модули
│ ├── core/
│ │ ├── base.yaml # базовая инфраструктура
│ │ └── common/ # shared components (schemas, responses, parameters)
│ ├── users.yaml # 7 методов управления пользователями
│ ├── groups.yaml # 12 методов управления группами
│ ├── certificates.yaml # 10 методов сертификатов
│ ├── learning.yaml # 8 методов обучения
│ └── reports.yaml # 8 методов отчётов
│
├── tools/ # сборщик и вспомогательные скрипты
│ ├── package.json # зависимости для build.js
│ ├── build.js # объединяет specs/* в space-platform-api.yaml
│ └── add-try-link.js # инжектирует логотип и скрипты в HTML
│
├── docs/ # сгенерированная документация
│ ├── index.html # итоговая красивая спека (Redoc)
│ ├── space-platform-api.yaml
│ └── img/
│ └── logo.svg
│
├── bundles/
│ └── complete-api.yaml # симлинк → ../space-platform-api.yaml
│
├── Dockerfile # контейнеризация
├── nginx.conf # конфиг nginx для контейнера
└── README.md # этот файл
| Команда | Описание |
|---|---|
npm run lint |
Проверить YAML на ошибки (redocly lint) |
npm run build:modules |
Собрать spec: tools/build.js |
npm run bundle |
Собрать + создать симлинк |
npm run build-docs |
Собрать + сгенерировать HTML |
npm run watch |
Автоматически пересобирать при изменении specs/ |
npm run ci:spec |
lint + bundle (для CI/CD) |
Образ автоматически собирается в GitHub Actions при каждом push:
# запустить готовый образ с Docker Hub
docker run -d -p 3000:80 --name space-api ghcr.io/tkavelli/reezonly-space-openapi:latest
# проверить логи
docker logs -f space-api
# остановить контейнер
docker stop space-api && docker rm space-api# собрать образ
docker build -t reezonly-space-openapi .
# запустить контейнер
docker run -d -p 3000:80 --name space-api reezonly-space-openapi
# проверить логи
docker logs -f space-api
# остановить контейнер
docker stop space-api && docker rm space-apiПри каждом push в main GitHub Actions автоматически собирает и публикует образ:
ghcr.io/tkavelli/reezonly-space-openapi:latest— последняя версия из mainghcr.io/tkavelli/reezonly-space-openapi:main— текущий branchghcr.io/tkavelli/reezonly-space-openapi:sha-<commit>— конкретный коммит
Скачать образ:
docker pull ghcr.io/tkavelli/reezonly-space-openapi:latestПроверить статус сборки: https://github.com/tkavelli/reezonly-space-openapi/actions
- REFACTOR_PLAN.md — план архитектуры и текущие задачи
- best_practicies.md — стандарты и best practices для OpenAPI
- CUSTOMIZATION.md — кастомизация Redoc UI
При push в main:
- Восстанавливает зависимости:
npm ci && npm ci --prefix tools - Генерирует документацию:
npm run build-docs - Деплоит в GitHub Pages: https://tkavelli.github.io/reezonly-space-openapi
При push в main:
- Собирает Docker образ
- Публикует в GitHub Container Registry (ghcr.io)
- Доступен на:
ghcr.io/tkavelli/reezonly-space-openapi:latest
Все workflows: https://github.com/tkavelli/reezonly-space-openapi/actions
Что происходит:
pages.yml— деплой на GitHub Pages (через nginx в докере)docker.yml— сборка и публикация Docker образа
- Отредактируй соответствующий файл в
specs/(e.g.,specs/users.yaml) - Добавь
descriptionко всем полям и параметрам (требование линтера) npm run lint— проверь синтаксисnpm run build-docs— собери и посмотри результатgit add . && git commit && git push— задеплоится автоматически на GitHub Pages
npm run lint && npm run build-docsЕсли всё зелёное — коммитить можно.
npm run build-docs
python3 -m http.server 3000
open http://localhost:3000/docsРепо содержит только исходники:
- ✅ Исходные YAML файлы (
specs/*) - ✅ Конфиги и скрипты (
redocly.yaml,tools/build.js) - ✅
package.jsonиpackage-lock.json - ❌ node_modules (исключён, используй
npm ci) - ❌ Generated files (
docs/index.html,space-platform-api.yamlиз bundle)
Это обеспечивает чистоту репозитория (~200 KB вместо 200+ MB).
Q: Где редактировать API?
A: В specs/ директории, каждый модуль в отдельном файле.
Q: Как запустить локально?
A: npm ci && npm run build-docs && python3 -m http.server 3000
Q: Где документация по API?
A: В docs/index.html после npm run build-docs
Q: Как задеплоить изменения?
A: Просто git push в main — GitHub Actions сам всё сделает.
Q: Почему генерируется HTML? A: Redoc преобразует YAML в красивую интерактивную документацию с примерами и "Try It Out".