From 47991bd5f38e9da688e36ffc4a49a99c2dc4e81b Mon Sep 17 00:00:00 2001 From: zenfun Date: Fri, 2 Jan 2026 23:22:36 +0800 Subject: [PATCH] docs(api): update swagger documentation for traffic charts and trends Regenerate API documentation to reflect recent statistics features: - Add definition for new `/admin/logs/stats/traffic-chart` endpoint - Update dashboard summary with `include_trends` parameter and new time periods - Add `DashboardTrends` and `TrafficChartResponse` data structures - Update alert types to include `traffic_spike --- docs/docs.go | 178 +++++++++++++++++++++++++++++++++++++++++++++- docs/swagger.json | 178 +++++++++++++++++++++++++++++++++++++++++++++- docs/swagger.yaml | 117 +++++++++++++++++++++++++++++- 3 files changed, 467 insertions(+), 6 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 27c8b04..613648b 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -86,7 +86,7 @@ const docTemplate = `{ }, { "type": "string", - "description": "filter by type (rate_limit, error_spike, quota_exceeded, key_disabled, key_expired, provider_down)", + "description": "filter by type (rate_limit, error_spike, quota_exceeded, key_disabled, key_expired, provider_down, traffic_spike)", "name": "type", "in": "query" } @@ -1183,7 +1183,7 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "time period: today, week, month, all", + "description": "time period: today, week, month, last7d, last30d, all", "name": "period", "in": "query" }, @@ -1198,6 +1198,12 @@ const docTemplate = `{ "description": "unix seconds", "name": "until", "in": "query" + }, + { + "type": "boolean", + "description": "include trend data comparing to previous period", + "name": "include_trends", + "in": "query" } ], "responses": { @@ -1610,6 +1616,73 @@ const docTemplate = `{ } } }, + "/admin/logs/stats/traffic-chart": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get time × model aggregated data for stacked traffic charts. Returns time buckets with per-model breakdown.", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Traffic chart data (admin)", + "parameters": [ + { + "enum": [ + "hour", + "minute" + ], + "type": "string", + "description": "Time granularity: hour (default) or minute", + "name": "granularity", + "in": "query" + }, + { + "type": "integer", + "description": "Start time (unix seconds), defaults to 24h ago", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "End time (unix seconds), defaults to now", + "name": "until", + "in": "query" + }, + { + "type": "integer", + "description": "Number of top models to return (1-20), defaults to 5", + "name": "top_n", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.TrafficChartResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, "/admin/logs/webhook": { "get": { "security": [ @@ -4510,6 +4583,9 @@ const docTemplate = `{ "latency_ms": { "type": "integer" }, + "master_id": { + "type": "integer" + }, "model": { "type": "string" }, @@ -5138,11 +5214,36 @@ const docTemplate = `{ "$ref": "#/definitions/internal_api.TopModelStat" } }, + "trends": { + "description": "Only present when include_trends=true", + "allOf": [ + { + "$ref": "#/definitions/internal_api.DashboardTrends" + } + ] + }, "updated_at": { "type": "integer" } } }, + "internal_api.DashboardTrends": { + "type": "object", + "properties": { + "error_rate": { + "$ref": "#/definitions/internal_api.TrendInfo" + }, + "latency": { + "$ref": "#/definitions/internal_api.TrendInfo" + }, + "requests": { + "$ref": "#/definitions/internal_api.TrendInfo" + }, + "tokens": { + "$ref": "#/definitions/internal_api.TrendInfo" + } + } + }, "internal_api.DeleteLogsRequest": { "type": "object", "properties": { @@ -5837,6 +5938,79 @@ const docTemplate = `{ } } }, + "internal_api.TrafficBucket": { + "type": "object", + "properties": { + "breakdown": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/internal_api.TrafficMetrics" + } + }, + "time": { + "type": "string" + }, + "timestamp": { + "type": "integer" + }, + "total": { + "$ref": "#/definitions/internal_api.TrafficMetrics" + } + } + }, + "internal_api.TrafficChartResponse": { + "type": "object", + "properties": { + "buckets": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.TrafficBucket" + } + }, + "granularity": { + "type": "string" + }, + "models": { + "type": "array", + "items": { + "type": "string" + } + }, + "since": { + "type": "integer" + }, + "until": { + "type": "integer" + } + } + }, + "internal_api.TrafficMetrics": { + "type": "object", + "properties": { + "count": { + "type": "integer" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + } + } + }, + "internal_api.TrendInfo": { + "type": "object", + "properties": { + "delta": { + "description": "Percentage change from previous period (nil if no baseline)", + "type": "number" + }, + "direction": { + "description": "\"up\", \"down\", \"stable\", or \"new\" (no baseline)", + "type": "string" + } + } + }, "internal_api.UpdateAccessRequest": { "type": "object", "properties": { diff --git a/docs/swagger.json b/docs/swagger.json index 7ff48eb..a2ab2c8 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -80,7 +80,7 @@ }, { "type": "string", - "description": "filter by type (rate_limit, error_spike, quota_exceeded, key_disabled, key_expired, provider_down)", + "description": "filter by type (rate_limit, error_spike, quota_exceeded, key_disabled, key_expired, provider_down, traffic_spike)", "name": "type", "in": "query" } @@ -1177,7 +1177,7 @@ "parameters": [ { "type": "string", - "description": "time period: today, week, month, all", + "description": "time period: today, week, month, last7d, last30d, all", "name": "period", "in": "query" }, @@ -1192,6 +1192,12 @@ "description": "unix seconds", "name": "until", "in": "query" + }, + { + "type": "boolean", + "description": "include trend data comparing to previous period", + "name": "include_trends", + "in": "query" } ], "responses": { @@ -1604,6 +1610,73 @@ } } }, + "/admin/logs/stats/traffic-chart": { + "get": { + "security": [ + { + "AdminAuth": [] + } + ], + "description": "Get time × model aggregated data for stacked traffic charts. Returns time buckets with per-model breakdown.", + "produces": [ + "application/json" + ], + "tags": [ + "admin" + ], + "summary": "Traffic chart data (admin)", + "parameters": [ + { + "enum": [ + "hour", + "minute" + ], + "type": "string", + "description": "Time granularity: hour (default) or minute", + "name": "granularity", + "in": "query" + }, + { + "type": "integer", + "description": "Start time (unix seconds), defaults to 24h ago", + "name": "since", + "in": "query" + }, + { + "type": "integer", + "description": "End time (unix seconds), defaults to now", + "name": "until", + "in": "query" + }, + { + "type": "integer", + "description": "Number of top models to return (1-20), defaults to 5", + "name": "top_n", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/internal_api.TrafficChartResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/gin.H" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/gin.H" + } + } + } + } + }, "/admin/logs/webhook": { "get": { "security": [ @@ -4504,6 +4577,9 @@ "latency_ms": { "type": "integer" }, + "master_id": { + "type": "integer" + }, "model": { "type": "string" }, @@ -5132,11 +5208,36 @@ "$ref": "#/definitions/internal_api.TopModelStat" } }, + "trends": { + "description": "Only present when include_trends=true", + "allOf": [ + { + "$ref": "#/definitions/internal_api.DashboardTrends" + } + ] + }, "updated_at": { "type": "integer" } } }, + "internal_api.DashboardTrends": { + "type": "object", + "properties": { + "error_rate": { + "$ref": "#/definitions/internal_api.TrendInfo" + }, + "latency": { + "$ref": "#/definitions/internal_api.TrendInfo" + }, + "requests": { + "$ref": "#/definitions/internal_api.TrendInfo" + }, + "tokens": { + "$ref": "#/definitions/internal_api.TrendInfo" + } + } + }, "internal_api.DeleteLogsRequest": { "type": "object", "properties": { @@ -5831,6 +5932,79 @@ } } }, + "internal_api.TrafficBucket": { + "type": "object", + "properties": { + "breakdown": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/internal_api.TrafficMetrics" + } + }, + "time": { + "type": "string" + }, + "timestamp": { + "type": "integer" + }, + "total": { + "$ref": "#/definitions/internal_api.TrafficMetrics" + } + } + }, + "internal_api.TrafficChartResponse": { + "type": "object", + "properties": { + "buckets": { + "type": "array", + "items": { + "$ref": "#/definitions/internal_api.TrafficBucket" + } + }, + "granularity": { + "type": "string" + }, + "models": { + "type": "array", + "items": { + "type": "string" + } + }, + "since": { + "type": "integer" + }, + "until": { + "type": "integer" + } + } + }, + "internal_api.TrafficMetrics": { + "type": "object", + "properties": { + "count": { + "type": "integer" + }, + "tokens_in": { + "type": "integer" + }, + "tokens_out": { + "type": "integer" + } + } + }, + "internal_api.TrendInfo": { + "type": "object", + "properties": { + "delta": { + "description": "Percentage change from previous period (nil if no baseline)", + "type": "number" + }, + "direction": { + "description": "\"up\", \"down\", \"stable\", or \"new\" (no baseline)", + "type": "string" + } + } + }, "internal_api.UpdateAccessRequest": { "type": "object", "properties": { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index bc40a57..08a0550 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -179,6 +179,8 @@ definitions: type: integer latency_ms: type: integer + master_id: + type: integer model: type: string provider_id: @@ -594,9 +596,24 @@ definitions: items: $ref: '#/definitions/internal_api.TopModelStat' type: array + trends: + allOf: + - $ref: '#/definitions/internal_api.DashboardTrends' + description: Only present when include_trends=true updated_at: type: integer type: object + internal_api.DashboardTrends: + properties: + error_rate: + $ref: '#/definitions/internal_api.TrendInfo' + latency: + $ref: '#/definitions/internal_api.TrendInfo' + requests: + $ref: '#/definitions/internal_api.TrendInfo' + tokens: + $ref: '#/definitions/internal_api.TrendInfo' + type: object internal_api.DeleteLogsRequest: properties: before: @@ -1053,6 +1070,54 @@ definitions: tokens: type: integer type: object + internal_api.TrafficBucket: + properties: + breakdown: + additionalProperties: + $ref: '#/definitions/internal_api.TrafficMetrics' + type: object + time: + type: string + timestamp: + type: integer + total: + $ref: '#/definitions/internal_api.TrafficMetrics' + type: object + internal_api.TrafficChartResponse: + properties: + buckets: + items: + $ref: '#/definitions/internal_api.TrafficBucket' + type: array + granularity: + type: string + models: + items: + type: string + type: array + since: + type: integer + until: + type: integer + type: object + internal_api.TrafficMetrics: + properties: + count: + type: integer + tokens_in: + type: integer + tokens_out: + type: integer + type: object + internal_api.TrendInfo: + properties: + delta: + description: Percentage change from previous period (nil if no baseline) + type: number + direction: + description: '"up", "down", "stable", or "new" (no baseline)' + type: string + type: object internal_api.UpdateAccessRequest: properties: default_namespace: @@ -1349,7 +1414,7 @@ paths: name: severity type: string - description: filter by type (rate_limit, error_spike, quota_exceeded, key_disabled, - key_expired, provider_down) + key_expired, provider_down, traffic_spike) in: query name: type type: string @@ -2045,7 +2110,7 @@ paths: description: Returns aggregated metrics for dashboard display including requests, tokens, latency, masters, keys, and provider keys statistics parameters: - - description: 'time period: today, week, month, all' + - description: 'time period: today, week, month, last7d, last30d, all' in: query name: period type: string @@ -2057,6 +2122,10 @@ paths: in: query name: until type: integer + - description: include trend data comparing to previous period + in: query + name: include_trends + type: boolean produces: - application/json responses: @@ -2331,6 +2400,50 @@ paths: summary: Log stats (admin) tags: - admin + /admin/logs/stats/traffic-chart: + get: + description: Get time × model aggregated data for stacked traffic charts. Returns + time buckets with per-model breakdown. + parameters: + - description: 'Time granularity: hour (default) or minute' + enum: + - hour + - minute + in: query + name: granularity + type: string + - description: Start time (unix seconds), defaults to 24h ago + in: query + name: since + type: integer + - description: End time (unix seconds), defaults to now + in: query + name: until + type: integer + - description: Number of top models to return (1-20), defaults to 5 + in: query + name: top_n + type: integer + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/internal_api.TrafficChartResponse' + "400": + description: Bad Request + schema: + $ref: '#/definitions/gin.H' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/gin.H' + security: + - AdminAuth: [] + summary: Traffic chart data (admin) + tags: + - admin /admin/logs/webhook: get: description: Returns current webhook notification config