Add OpenAPI specification for system-log service.
This commit is contained in:
emelinda
parent
5f7fe11748
commit
f184c7b8d9
427
apps/system-log/openapi.yaml
Normal file
427
apps/system-log/openapi.yaml
Normal file
@ -0,0 +1,427 @@
|
|||||||
|
openapi: 3.0.3
|
||||||
|
|
||||||
|
info:
|
||||||
|
title: system-log API
|
||||||
|
version: "1.0.0"
|
||||||
|
description: |
|
||||||
|
REST API сервиса **system-log** (`platform/system-log`) — приём и выборка
|
||||||
|
записей журнала системных событий (кто, над чем и какое действие совершил).
|
||||||
|
|
||||||
|
Сервис написан на Go (фреймворк **Fiber v2**). Роутинг собирается в
|
||||||
|
`internal/controller/http/v0`: базовая группа `/api` → подгруппа `v0` →
|
||||||
|
ресурс `/system_log`. Плюс служебный эндпоинт `/ping`.
|
||||||
|
|
||||||
|
### Аутентификация
|
||||||
|
Аутентификация на уровне приложения не настроена — эндпоинты доступны без
|
||||||
|
авторизации. Ограничение доступа обеспечивается сетевым слоем (ClusterIP /
|
||||||
|
Istio), а не самим сервисом.
|
||||||
|
|
||||||
|
### Пагинация
|
||||||
|
Списочные ответы возвращают объект `{ count, limit, offset, next, prev, result }`.
|
||||||
|
Управление — параметрами `limit` и `offset`. Значения по умолчанию:
|
||||||
|
`limit = 100`, `offset = 0` (константы `_defaultLimit` / `_defaultOffset`
|
||||||
|
в `internal/controller/http/v0/systemlog/controller.go`). Ссылки `next`/`prev`
|
||||||
|
формируются в `pkg/pagination`. У эндпоинта поиска (`POST /search`) полей
|
||||||
|
`next`/`prev` нет.
|
||||||
|
|
||||||
|
### Фильтрация
|
||||||
|
Массивные фильтры (`actor_ids`, `event_names`, `model_names`, `instance_ids`,
|
||||||
|
`target_ids`, `company_ids`, `statuses`, `message`) в GET-запросе передаются
|
||||||
|
списком значений через запятую и парсятся Fiber `QueryParser`. Поля
|
||||||
|
`instance_uuids` и `resource_uuids` разбираются вручную (`strings.Split` +
|
||||||
|
`uuid.Parse`) — при невалидном UUID возвращается `400`.
|
||||||
|
|
||||||
|
### Замечания (расхождения кода)
|
||||||
|
- `metadata` в фильтре объявлено как `map[string]interface{}` с query-тегом,
|
||||||
|
но при передаче в query-строке Fiber не восстановит вложенный объект —
|
||||||
|
фильтрация по `metadata` практически применима через тело `POST /search`.
|
||||||
|
- Поле `is_processed_by_worker` присутствует в фильтре, но отдаётся в выборку
|
||||||
|
наравне с остальными; используется воркером обогащения.
|
||||||
|
- Ответ `POST /system_log/` при успехе — простая строка `"OK"` (не объект).
|
||||||
|
|
||||||
|
servers:
|
||||||
|
- url: https://api.sarex.io
|
||||||
|
description: Production (ingress)
|
||||||
|
- url: https://stage-api.sarex.io
|
||||||
|
description: Stage (ingress)
|
||||||
|
- url: http://backend-svc.system-log.svc.cluster.local
|
||||||
|
description: Внутрикластерный адрес (ClusterIP, порт 80 → 8000)
|
||||||
|
- url: http://localhost:8888
|
||||||
|
description: Локальный запуск (config.env)
|
||||||
|
|
||||||
|
tags:
|
||||||
|
- name: system_log
|
||||||
|
description: Записи журнала системных событий
|
||||||
|
- name: service
|
||||||
|
description: Служебные эндпоинты
|
||||||
|
|
||||||
|
paths:
|
||||||
|
# ==========================================================================
|
||||||
|
# Service
|
||||||
|
# ==========================================================================
|
||||||
|
/ping:
|
||||||
|
get:
|
||||||
|
tags: [service]
|
||||||
|
summary: Проверка живости
|
||||||
|
description: Liveness/readiness-проба (используется в probes деплоймента). Всегда `200 OK` без тела.
|
||||||
|
operationId: ping
|
||||||
|
security: []
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: OK
|
||||||
|
|
||||||
|
# ==========================================================================
|
||||||
|
# System log
|
||||||
|
# ==========================================================================
|
||||||
|
/api/v0/system_log/:
|
||||||
|
get:
|
||||||
|
tags: [system_log]
|
||||||
|
summary: Список записей журнала (с фильтрами)
|
||||||
|
description: |
|
||||||
|
Возвращает отфильтрованные записи журнала с пагинацией.
|
||||||
|
Массивные параметры принимают список значений через запятую.
|
||||||
|
operationId: getSystemLogRecords
|
||||||
|
parameters:
|
||||||
|
- $ref: '#/components/parameters/Limit'
|
||||||
|
- $ref: '#/components/parameters/Offset'
|
||||||
|
- name: actor_ids
|
||||||
|
in: query
|
||||||
|
description: ID авторов событий; список значений через запятую
|
||||||
|
example: "1,2,3"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: event_names
|
||||||
|
in: query
|
||||||
|
description: Названия событий (напр. create, edit, delete, transfer); через запятую
|
||||||
|
example: "create,edit,delete"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: model_names
|
||||||
|
in: query
|
||||||
|
description: Названия моделей (напр. document, bundle, project); через запятую
|
||||||
|
example: "document,bundle"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: instance_ids
|
||||||
|
in: query
|
||||||
|
description: ID сущностей; список значений через запятую
|
||||||
|
example: "1,2,3"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: instance_uuids
|
||||||
|
in: query
|
||||||
|
description: UUID сущностей; список значений через запятую (валидируются как UUID)
|
||||||
|
example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: resource_uuids
|
||||||
|
in: query
|
||||||
|
description: UUID ресурсов; список значений через запятую (валидируются как UUID)
|
||||||
|
schema: { type: string }
|
||||||
|
- name: registered_at_gte
|
||||||
|
in: query
|
||||||
|
description: Нижняя граница времени регистрации (>=)
|
||||||
|
example: "2025-02-16T15:04:05Z"
|
||||||
|
schema: { type: string, format: date-time }
|
||||||
|
- name: registered_at_lte
|
||||||
|
in: query
|
||||||
|
description: Верхняя граница времени регистрации (<=)
|
||||||
|
example: "2025-02-16T15:04:05Z"
|
||||||
|
schema: { type: string, format: date-time }
|
||||||
|
- name: instance_path
|
||||||
|
in: query
|
||||||
|
description: Путь сущности (ltree), точное совпадение
|
||||||
|
example: "1.79899.80131"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: target_ids
|
||||||
|
in: query
|
||||||
|
description: ID целей; список значений через запятую
|
||||||
|
example: "1,2,3"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: target_path
|
||||||
|
in: query
|
||||||
|
description: Путь цели (ltree), точное совпадение
|
||||||
|
example: "4.3.2.1"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: company_ids
|
||||||
|
in: query
|
||||||
|
description: ID компаний; список значений через запятую
|
||||||
|
example: "1,2,3"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: statuses
|
||||||
|
in: query
|
||||||
|
description: Подстатусы события; список значений через запятую
|
||||||
|
example: "add_bundle,delete_bundle,rename_document"
|
||||||
|
schema: { type: string }
|
||||||
|
- name: message
|
||||||
|
in: query
|
||||||
|
description: Сообщения; список значений через запятую
|
||||||
|
schema: { type: string }
|
||||||
|
- name: is_processed_by_worker
|
||||||
|
in: query
|
||||||
|
description: Признак обработки записи воркером обогащения
|
||||||
|
schema: { type: boolean }
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: OK
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema: { $ref: '#/components/schemas/SystemLogListResponse' }
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
'500':
|
||||||
|
$ref: '#/components/responses/InternalError'
|
||||||
|
post:
|
||||||
|
tags: [system_log]
|
||||||
|
summary: Создать записи журнала
|
||||||
|
description: |
|
||||||
|
Принимает пакет записей в поле `system_logs`. Для каждой записи должно
|
||||||
|
быть задано **ровно одно** из `instance_id` / `instance_uuid`
|
||||||
|
(не оба и не ни одного — иначе `400`). Обязательны `event_name` и
|
||||||
|
`model_name`. При успехе возвращается строка `"OK"`.
|
||||||
|
operationId: createSystemLogRecords
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema: { $ref: '#/components/schemas/SystemLogCreateRequest' }
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Записи созданы
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
example: "OK"
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
'500':
|
||||||
|
$ref: '#/components/responses/InternalError'
|
||||||
|
|
||||||
|
/api/v0/system_log/search:
|
||||||
|
post:
|
||||||
|
tags: [system_log]
|
||||||
|
summary: Поиск записей журнала (фильтры в теле)
|
||||||
|
description: |
|
||||||
|
Аналог GET-выборки, но фильтры передаются в теле запроса
|
||||||
|
(`filters`). Позволяет использовать сложные фильтры (в т.ч. `metadata`),
|
||||||
|
которые неудобно кодировать в query-строке. В ответе нет `next`/`prev`.
|
||||||
|
operationId: searchSystemLogs
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema: { $ref: '#/components/schemas/SystemLogSearchRequest' }
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: OK
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema: { $ref: '#/components/schemas/SystemLogSearchResponse' }
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
'500':
|
||||||
|
$ref: '#/components/responses/InternalError'
|
||||||
|
|
||||||
|
# ============================================================================
|
||||||
|
components:
|
||||||
|
parameters:
|
||||||
|
Limit:
|
||||||
|
name: limit
|
||||||
|
in: query
|
||||||
|
description: Кол-во записей на странице
|
||||||
|
schema: { type: integer, format: uint64, default: 100 }
|
||||||
|
Offset:
|
||||||
|
name: offset
|
||||||
|
in: query
|
||||||
|
description: Смещение от начала выборки
|
||||||
|
schema: { type: integer, format: uint64, default: 0, minimum: 0 }
|
||||||
|
|
||||||
|
responses:
|
||||||
|
BadRequest:
|
||||||
|
description: Ошибка разбора/валидации запроса
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema: { $ref: '#/components/schemas/ControllerError' }
|
||||||
|
InternalError:
|
||||||
|
description: Внутренняя ошибка сервиса
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema: { $ref: '#/components/schemas/ControllerError' }
|
||||||
|
|
||||||
|
schemas:
|
||||||
|
# ---- Общие ----
|
||||||
|
ControllerError:
|
||||||
|
type: object
|
||||||
|
description: Формат ошибки (`internal/controller/errors.go`, `ErrorToResponse`).
|
||||||
|
properties:
|
||||||
|
message: { type: string, example: "error parse body" }
|
||||||
|
status_code: { type: integer, example: 400 }
|
||||||
|
|
||||||
|
# ---- Доменная запись ----
|
||||||
|
SystemLog:
|
||||||
|
type: object
|
||||||
|
description: Запись журнала системных событий (`internal/entity/system_log.go`).
|
||||||
|
properties:
|
||||||
|
actor_id:
|
||||||
|
type: integer
|
||||||
|
format: uint64
|
||||||
|
description: ID автора события
|
||||||
|
example: 1023
|
||||||
|
event_name:
|
||||||
|
type: string
|
||||||
|
description: Название события (напр. edit, create, copy)
|
||||||
|
example: "edit"
|
||||||
|
model_name:
|
||||||
|
type: string
|
||||||
|
description: Над какой сущностью произошло событие (напр. document, inspection)
|
||||||
|
example: "document"
|
||||||
|
instance_id:
|
||||||
|
type: integer
|
||||||
|
format: uint64
|
||||||
|
nullable: true
|
||||||
|
description: ID сущности (для моделей с числовым ключом)
|
||||||
|
example: 80131
|
||||||
|
instance_uuid:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
nullable: true
|
||||||
|
description: UUID сущности (для моделей с UUID-ключом)
|
||||||
|
registered_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
nullable: true
|
||||||
|
description: Время регистрации события
|
||||||
|
example: "2023-05-04T08:09:53.852916Z"
|
||||||
|
instance_path:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: Путь сущности (ltree)
|
||||||
|
example: "1.79899.80131"
|
||||||
|
target_id:
|
||||||
|
type: integer
|
||||||
|
format: uint64
|
||||||
|
nullable: true
|
||||||
|
description: ID цели события
|
||||||
|
company_id:
|
||||||
|
type: integer
|
||||||
|
format: uint64
|
||||||
|
nullable: true
|
||||||
|
description: ID компании (может обогащаться воркером)
|
||||||
|
example: 1
|
||||||
|
metadata:
|
||||||
|
type: object
|
||||||
|
additionalProperties: true
|
||||||
|
description: Произвольные дополнительные данные о событии
|
||||||
|
example: { "document_name": "КСГ.pdf", "count_bundle": 3 }
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: Произвольное сообщение
|
||||||
|
example: "bundle was deleted from document"
|
||||||
|
status:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: Подстатус события
|
||||||
|
example: "delete_bundle"
|
||||||
|
resource_uuid:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
nullable: true
|
||||||
|
description: UUID связанного ресурса
|
||||||
|
target_path:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: Путь цели (ltree)
|
||||||
|
required: [event_name, model_name]
|
||||||
|
|
||||||
|
# ---- Запросы ----
|
||||||
|
SystemLogCreateRequest:
|
||||||
|
type: object
|
||||||
|
description: >
|
||||||
|
Пакет записей для создания. Для каждой записи обязательно ровно одно из
|
||||||
|
instance_id / instance_uuid.
|
||||||
|
properties:
|
||||||
|
system_logs:
|
||||||
|
type: array
|
||||||
|
minItems: 1
|
||||||
|
items: { $ref: '#/components/schemas/SystemLog' }
|
||||||
|
required: [system_logs]
|
||||||
|
|
||||||
|
SystemLogFilter:
|
||||||
|
type: object
|
||||||
|
description: Набор фильтров выборки (`entity.SystemLogFilter`).
|
||||||
|
properties:
|
||||||
|
limit: { type: integer, format: uint64, default: 100 }
|
||||||
|
offset: { type: integer, format: uint64, default: 0 }
|
||||||
|
actor_ids:
|
||||||
|
type: array
|
||||||
|
items: { type: integer, format: uint64 }
|
||||||
|
event_names:
|
||||||
|
type: array
|
||||||
|
items: { type: string }
|
||||||
|
model_names:
|
||||||
|
type: array
|
||||||
|
items: { type: string }
|
||||||
|
instance_ids:
|
||||||
|
type: array
|
||||||
|
items: { type: integer, format: uint64 }
|
||||||
|
instance_uuids:
|
||||||
|
type: array
|
||||||
|
items: { type: string, format: uuid }
|
||||||
|
registered_at_gte: { type: string, format: date-time, nullable: true }
|
||||||
|
registered_at_lte: { type: string, format: date-time, nullable: true }
|
||||||
|
instance_path: { type: string, nullable: true }
|
||||||
|
target_ids:
|
||||||
|
type: array
|
||||||
|
items: { type: integer, format: uint64 }
|
||||||
|
target_path: { type: string, nullable: true }
|
||||||
|
company_ids:
|
||||||
|
type: array
|
||||||
|
items: { type: integer, format: uint64 }
|
||||||
|
statuses:
|
||||||
|
type: array
|
||||||
|
items: { type: string }
|
||||||
|
message: { type: string, nullable: true }
|
||||||
|
metadata:
|
||||||
|
type: object
|
||||||
|
additionalProperties: true
|
||||||
|
resource_uuids:
|
||||||
|
type: array
|
||||||
|
items: { type: string, format: uuid }
|
||||||
|
is_processed_by_worker: { type: boolean, nullable: true }
|
||||||
|
|
||||||
|
SystemLogSearchRequest:
|
||||||
|
type: object
|
||||||
|
description: Тело запроса поиска (`SearchParams` в `dto.go`).
|
||||||
|
properties:
|
||||||
|
limit: { type: integer, format: uint64, default: 100 }
|
||||||
|
offset: { type: integer, format: uint64, default: 0 }
|
||||||
|
filters: { $ref: '#/components/schemas/SystemLogFilter' }
|
||||||
|
|
||||||
|
# ---- Ответы ----
|
||||||
|
SystemLogListResponse:
|
||||||
|
type: object
|
||||||
|
description: Ответ списочной выборки (`entity.SystemLogRecordsRequest`).
|
||||||
|
properties:
|
||||||
|
count: { type: integer, format: uint64, example: 1226 }
|
||||||
|
limit: { type: integer, format: uint64, nullable: true, example: 100 }
|
||||||
|
offset: { type: integer, format: uint64, nullable: true, example: 0 }
|
||||||
|
next:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
example: "http://localhost:8888/api/v0/system_log?limit=100&offset=100"
|
||||||
|
prev:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
result:
|
||||||
|
type: array
|
||||||
|
items: { $ref: '#/components/schemas/SystemLog' }
|
||||||
|
required: [count, result]
|
||||||
|
|
||||||
|
SystemLogSearchResponse:
|
||||||
|
type: object
|
||||||
|
description: Ответ поиска (`entity.SystemLogRecordsSearch`) — без next/prev.
|
||||||
|
properties:
|
||||||
|
count: { type: integer, format: uint64, example: 1226 }
|
||||||
|
limit: { type: integer, format: uint64, nullable: true, example: 100 }
|
||||||
|
offset: { type: integer, format: uint64, nullable: true, example: 0 }
|
||||||
|
result:
|
||||||
|
type: array
|
||||||
|
items: { $ref: '#/components/schemas/SystemLog' }
|
||||||
|
required: [count, result]
|
||||||
Loading…
Reference in New Issue
Block a user