index

API

src/golden/**/*Controller.ts · Swagger: /golden/api-docs/v2

REST API stack-golden для електрон-клієнта, оператор-клієнта, адмін-зони і службових інтеграцій. Контракт автоматично генерується з декораторів routing-controllers + routing-controllers-openapi для мігрованих контролерів. Legacy-контролери (на BaseController.bindRoutes) у Swagger не з’являються — лише в expressListEndpoints логі при старті.

Live Swagger

• Локально: http://localhost:81/golden/api-docs/v2
• Прод: <TBD>

Один UI на всі мігровані контролери. Згруповано тегами (Admin, Statistics V2, Electron API).

Інвентар API-груп

Конвенція відповідей

Усі ендпоінти повертають HTTP 200 з body одного з двох форматів:

// success
{ "success": true, "data": <payload> }
 
// error
{ "success": false, "data": null|<data>, "message": "...", "statusCode": <code>, "context": "..." }

Реальний код у полі statusCode тіла, не у HTTP-статусі. Виняток — MiddlevareGuard без потрібної ролі повертає HTTP 400 + {success:false, data:{message:'Not allow role'}}, без токена — HTTP 401 з порожнім body.

Як додати нову групу в Swagger

Мігрувати legacy-контролер на routing-controllers. Чек-ліст у CLAUDE.md репо, секція “Як мігрувати legacy-контролер на routing-controllers”.

Після міграції контролер автоматично з’явиться в /golden/api-docs/v2 з тегом @OpenAPI({ tags: [...] }) і summary з @OpenAPI({ summary: '...' }) на кожному методі.

Зв’язки

• Контракт декларується через routing-controllers декоратори у відповідних *Controller.ts
• Інфраструктура mount + Swagger-spec — mountRoutingControllers з @it-monkeys/stack-commons
• Помилки нормалізуються через ExeptionFilter (з stack-commons)
• Гварди ролей — MiddlevareGuard (з stack-commons)