mirror of
https://github.com/EZ-Api/ez-api.git
synced 2026-01-13 17:47:51 +00:00
docs: update swagger docs for alerts API and minute-level stats
Add OpenAPI documentation for the new alerts management system: - CRUD endpoints for system alerts (/admin/alerts) - Alert acknowledgment and resolution endpoints - Alert statistics endpoint - Alert filtering by status, severity, and type Also document minute-level aggregation support for log stats with 6-hour time range limitation.
This commit is contained in:
zenfun
@@ -38,6 +38,360 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/admin/alerts": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"description": "List system alerts with optional filters",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"admin"
|
||||
],
|
||||
"summary": "List alerts",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "limit (default 50, max 200)",
|
||||
"name": "limit",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "offset",
|
||||
"name": "offset",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "filter by status (active, acknowledged, resolved, dismissed)",
|
||||
"name": "status",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "filter by severity (info, warning, critical)",
|
||||
"name": "severity",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "filter by type (rate_limit, error_spike, quota_exceeded, key_disabled, key_expired, provider_down)",
|
||||
"name": "type",
|
||||
"in": "query"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.ListAlertsResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"description": "Create a new system alert",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"admin"
|
||||
],
|
||||
"summary": "Create alert",
|
||||
"parameters": [
|
||||
{
|
||||
"description": "Alert data",
|
||||
"name": "request",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.CreateAlertRequest"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"201": {
|
||||
"description": "Created",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.AlertView"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/admin/alerts/stats": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"description": "Get alert count statistics by status and severity",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"admin"
|
||||
],
|
||||
"summary": "Alert statistics",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.AlertStats"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/admin/alerts/{id}": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"description": "Get a single alert by ID",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"admin"
|
||||
],
|
||||
"summary": "Get alert",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Alert ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.AlertView"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"delete": {
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"description": "Dismiss an alert (soft delete)",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"admin"
|
||||
],
|
||||
"summary": "Dismiss alert",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Alert ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/admin/alerts/{id}/ack": {
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"description": "Mark an alert as acknowledged",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"admin"
|
||||
],
|
||||
"summary": "Acknowledge alert",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Alert ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"description": "Ack data",
|
||||
"name": "request",
|
||||
"in": "body",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.AckAlertRequest"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.AlertView"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/admin/alerts/{id}/resolve": {
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"description": "Mark an alert as resolved",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"admin"
|
||||
],
|
||||
"summary": "Resolve alert",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Alert ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.AlertView"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/admin/api-keys": {
|
||||
"get": {
|
||||
"security": [
|
||||
@@ -1099,7 +1453,7 @@
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"description": "Aggregate log stats with basic filtering. Use group_by param for grouped statistics (model/day/month/hour). Without group_by returns LogStatsResponse; with group_by returns GroupedStatsResponse.",
|
||||
"description": "Aggregate log stats with basic filtering. Use group_by param for grouped statistics (model/day/month/hour/minute). Without group_by returns LogStatsResponse; with group_by returns GroupedStatsResponse. Note: minute-level aggregation is limited to 6-hour time ranges.",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@@ -1125,10 +1479,11 @@
|
||||
"model",
|
||||
"day",
|
||||
"month",
|
||||
"hour"
|
||||
"hour",
|
||||
"minute"
|
||||
],
|
||||
"type": "string",
|
||||
"description": "group by dimension: model, day, month, hour. Returns GroupedStatsResponse when specified.",
|
||||
"description": "group by dimension: model, day, month, hour, minute. Returns GroupedStatsResponse when specified.",
|
||||
"name": "group_by",
|
||||
"in": "query"
|
||||
}
|
||||
@@ -1140,6 +1495,12 @@
|
||||
"$ref": "#/definitions/internal_api.GroupedStatsResponse"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/gin.H"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
@@ -4336,6 +4697,14 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.AckAlertRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"acked_by": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.AdminUsageStatsResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4368,6 +4737,85 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.AlertStats": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"acknowledged": {
|
||||
"type": "integer"
|
||||
},
|
||||
"active": {
|
||||
"type": "integer"
|
||||
},
|
||||
"critical": {
|
||||
"type": "integer"
|
||||
},
|
||||
"info": {
|
||||
"type": "integer"
|
||||
},
|
||||
"resolved": {
|
||||
"type": "integer"
|
||||
},
|
||||
"total": {
|
||||
"type": "integer"
|
||||
},
|
||||
"warning": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.AlertView": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"acked_at": {
|
||||
"type": "integer"
|
||||
},
|
||||
"acked_by": {
|
||||
"type": "string"
|
||||
},
|
||||
"created_at": {
|
||||
"type": "integer"
|
||||
},
|
||||
"expires_at": {
|
||||
"type": "integer"
|
||||
},
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "string"
|
||||
},
|
||||
"related_id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"related_name": {
|
||||
"type": "string"
|
||||
},
|
||||
"related_type": {
|
||||
"type": "string"
|
||||
},
|
||||
"resolved_at": {
|
||||
"type": "integer"
|
||||
},
|
||||
"severity": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": {
|
||||
"type": "string"
|
||||
},
|
||||
"updated_at": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.BatchActionRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4427,6 +4875,43 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.CreateAlertRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"severity",
|
||||
"title",
|
||||
"type"
|
||||
],
|
||||
"properties": {
|
||||
"expires_at": {
|
||||
"type": "integer"
|
||||
},
|
||||
"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.CreateMasterRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
@@ -4522,6 +5007,10 @@
|
||||
"description": "For group_by=hour",
|
||||
"type": "string"
|
||||
},
|
||||
"minute": {
|
||||
"description": "For group_by=minute",
|
||||
"type": "string"
|
||||
},
|
||||
"model": {
|
||||
"description": "For group_by=model",
|
||||
"type": "string"
|
||||
@@ -4597,6 +5086,26 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.ListAlertsResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"items": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/internal_api.AlertView"
|
||||
}
|
||||
},
|
||||
"limit": {
|
||||
"type": "integer"
|
||||
},
|
||||
"offset": {
|
||||
"type": "integer"
|
||||
},
|
||||
"total": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.ListLogsResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
Reference in New Issue
Block a user