From 57797f38cb5f95419c997dd703606ca34f4e468e Mon Sep 17 00:00:00 2001 From: zenfun Date: Wed, 31 Dec 2025 14:18:42 +0800 Subject: [PATCH] docs(api): add alerts report endpoint and apikey-stats query params - Add internal /internal/alerts/report POST endpoint documentation - Add reportAlertEntry, reportAlertsRequest, reportAlertsResponse schemas - Add since/until query parameters to /admin/apikey-stats/summary endpoint --- docs/docs.go | 128 ++++++++++++++++++++++++++++++++++++++++++++++ docs/swagger.json | 128 ++++++++++++++++++++++++++++++++++++++++++++++ docs/swagger.yaml | 84 ++++++++++++++++++++++++++++++ 3 files changed, 340 insertions(+) diff --git a/docs/docs.go b/docs/docs.go index e710a80..e2543c4 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -737,6 +737,20 @@ const docTemplate = `{ "admin" ], "summary": "APIKey stats summary (admin)", + "parameters": [ + { + "type": "integer", + "description": "Start time (unix seconds)", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "End time (unix seconds)", + "name": "until", + "in": "query" + } + ], "responses": { "200": { "description": "OK", @@ -3385,6 +3399,52 @@ const docTemplate = `{ } } }, + "/internal/alerts/report": { + "post": { + "description": "Internal endpoint for Data Plane to report alerts to Control Plane", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "internal" + ], + "summary": "Report alerts from DP", + "parameters": [ + { + "description": "Alerts to report", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.reportAlertsRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.reportAlertsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, "/internal/apikey-stats/flush": { "post": { "description": "Internal endpoint for flushing accumulated APIKey stats from DP to CP database", @@ -5856,6 +5916,74 @@ const docTemplate = `{ } } }, + "internal_api.reportAlertEntry": { + "type": "object", + "required": [ + "severity", + "title", + "type" + ], + "properties": { + "fingerprint": { + "type": "string" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "string" + }, + "related_id": { + "type": "integer" + }, + "related_name": { + "type": "string" + }, + "related_type": { + "type": "string" + }, + "severity": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "internal_api.reportAlertsRequest": { + "type": "object", + "required": [ + "alerts" + ], + "properties": { + "alerts": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.reportAlertEntry" + } + } + } + }, + "internal_api.reportAlertsResponse": { + "type": "object", + "properties": { + "accepted": { + "type": "integer" + }, + "deduplicated": { + "type": "integer" + }, + "errors": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, "internal_api.statsFlushEntry": { "type": "object", "properties": { diff --git a/docs/swagger.json b/docs/swagger.json index 02ca4a9..63df210 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -731,6 +731,20 @@ "admin" ], "summary": "APIKey stats summary (admin)", + "parameters": [ + { + "type": "integer", + "description": "Start time (unix seconds)", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "End time (unix seconds)", + "name": "until", + "in": "query" + } + ], "responses": { "200": { "description": "OK", @@ -3379,6 +3393,52 @@ } } }, + "/internal/alerts/report": { + "post": { + "description": "Internal endpoint for Data Plane to report alerts to Control Plane", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "internal" + ], + "summary": "Report alerts from DP", + "parameters": [ + { + "description": "Alerts to report", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/internal_api.reportAlertsRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.reportAlertsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, "/internal/apikey-stats/flush": { "post": { "description": "Internal endpoint for flushing accumulated APIKey stats from DP to CP database", @@ -5850,6 +5910,74 @@ } } }, + "internal_api.reportAlertEntry": { + "type": "object", + "required": [ + "severity", + "title", + "type" + ], + "properties": { + "fingerprint": { + "type": "string" + }, + "message": { + "type": "string" + }, + "metadata": { + "type": "string" + }, + "related_id": { + "type": "integer" + }, + "related_name": { + "type": "string" + }, + "related_type": { + "type": "string" + }, + "severity": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "internal_api.reportAlertsRequest": { + "type": "object", + "required": [ + "alerts" + ], + "properties": { + "alerts": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.reportAlertEntry" + } + } + } + }, + "internal_api.reportAlertsResponse": { + "type": "object", + "properties": { + "accepted": { + "type": "integer" + }, + "deduplicated": { + "type": "integer" + }, + "errors": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, "internal_api.statsFlushEntry": { "type": "object", "properties": { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 9060ed5..ad005e1 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1164,6 +1164,51 @@ definitions: ref: type: string type: object + internal_api.reportAlertEntry: + properties: + fingerprint: + type: string + message: + type: string + metadata: + type: string + related_id: + type: integer + related_name: + type: string + related_type: + type: string + severity: + type: string + title: + type: string + type: + type: string + required: + - severity + - title + - type + type: object + internal_api.reportAlertsRequest: + properties: + alerts: + items: + $ref: '#/definitions/internal_api.reportAlertEntry' + type: array + required: + - alerts + type: object + internal_api.reportAlertsResponse: + properties: + accepted: + type: integer + deduplicated: + type: integer + errors: + items: + type: string + type: array + type: object internal_api.statsFlushEntry: properties: last_accessed_at: @@ -1681,6 +1726,15 @@ paths: /admin/apikey-stats/summary: get: description: Aggregate APIKey success/failure stats across all provider groups + parameters: + - description: Start time (unix seconds) + in: query + name: since + type: integer + - description: End time (unix seconds) + in: query + name: until + type: integer produces: - application/json responses: @@ -3386,6 +3440,36 @@ paths: summary: Get current identity tags: - auth + /internal/alerts/report: + post: + consumes: + - application/json + description: Internal endpoint for Data Plane to report alerts to Control Plane + parameters: + - description: Alerts to report + in: body + name: request + required: true + schema: + $ref: '#/definitions/internal_api.reportAlertsRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.reportAlertsResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + summary: Report alerts from DP + tags: + - internal /internal/apikey-stats/flush: post: consumes: