ruochen/ez-api
1
0
Fork 0
mirror of https://github.com/EZ-Api/ez-api.git synced 2026-01-13 17:47:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(swagger): update API documentation for log endpoints

Browse Source 
Add new response types and parameters for logs API:
- Add GroupedStatsItem and GroupedStatsResponse definitions
- Add ListLogsResponse and LogView definitions for detailed log records
- Add group_by enum parameter (model/day/month) to stats endpoint
- Update endpoint descriptions to clarify response types and request_body inclusion
- Update response schema references to use correct types
This commit is contained in:
zenfun
2025-12-26 11:12:47 +08:00
parent 3f1d006006
commit c83fe03892
4 changed files with 372 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
docs/docs.go
View File

@@ -861,7 +861,7 @@ const docTemplate = `{
"AdminAuth": []
}
],
"description": "List request logs with basic filtering/pagination",
"description": "List request logs with basic filtering/pagination. Returns full log records including request_body.",
"produces": [
"application/json"
],
@@ -923,7 +923,7 @@ const docTemplate = `{
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/internal_api.ListMasterLogsResponse"
"$ref": "#/definitions/internal_api.ListLogsResponse"
}
},
"500": {
@@ -991,7 +991,7 @@ const docTemplate = `{
"AdminAuth": []
}
],
"description": "Aggregate log stats with basic filtering",
"description": "Aggregate log stats with basic filtering. Use group_by param for grouped statistics (model/day/month). Without group_by returns LogStatsResponse; with group_by returns GroupedStatsResponse.",
"produces": [
"application/json"
],
@@ -1011,13 +1011,24 @@ const docTemplate = `{
"description": "unix seconds",
"name": "until",
"in": "query"
},
{
"enum": [
"model",
"day",
"month"
],
"type": "string",
"description": "group by dimension: model, day, month. Returns GroupedStatsResponse when specified.",
"name": "group_by",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"description": "Grouped stats (when group_by is specified)",
"schema": {
"$ref": "#/definitions/internal_api.LogStatsResponse"
"$ref": "#/definitions/internal_api.GroupedStatsResponse"
}
},
"500": {
@@ -4175,6 +4186,46 @@ const docTemplate = `{
}
}
},
"internal_api.GroupedStatsItem": {
"type": "object",
"properties": {
"avg_latency_ms": {
"type": "number"
},
"count": {
"type": "integer"
},
"date": {
"description": "For group_by=day",
"type": "string"
},
"model": {
"description": "For group_by=model",
"type": "string"
},
"month": {
"description": "For group_by=month",
"type": "string"
},
"tokens_in": {
"type": "integer"
},
"tokens_out": {
"type": "integer"
}
}
},
"internal_api.GroupedStatsResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/internal_api.GroupedStatsItem"
}
}
}
},
"internal_api.IssueChildKeyRequest": {
"type": "object",
"properties": {
@@ -4215,6 +4266,26 @@ const docTemplate = `{
}
}
},
"internal_api.ListLogsResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/internal_api.LogView"
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"total": {
"type": "integer"
}
}
},
"internal_api.ListMasterLogsResponse": {
"type": "object",
"properties": {
@@ -4259,6 +4330,65 @@ const docTemplate = `{
}
}
},
"internal_api.LogView": {
"type": "object",
"properties": {
"audit_reason": {
"type": "string"
},
"client_ip": {
"type": "string"
},
"created_at": {
"type": "integer"
},
"error_message": {
"type": "string"
},
"group": {
"type": "string"
},
"id": {
"type": "integer"
},
"key_id": {
"type": "integer"
},
"latency_ms": {
"type": "integer"
},
"model": {
"type": "string"
},
"provider_id": {
"type": "integer"
},
"provider_name": {
"type": "string"
},
"provider_type": {
"type": "string"
},
"request_body": {
"type": "string"
},
"request_size": {
"type": "integer"
},
"response_size": {
"type": "integer"
},
"status_code": {
"type": "integer"
},
"tokens_in": {
"type": "integer"
},
"tokens_out": {
"type": "integer"
}
}
},
"internal_api.ManageMasterRequest": {
"type": "object",
"required": [

140
docs/swagger.json
View File

@@ -855,7 +855,7 @@
"AdminAuth": []
}
],
"description": "List request logs with basic filtering/pagination",
"description": "List request logs with basic filtering/pagination. Returns full log records including request_body.",
"produces": [
"application/json"
],
@@ -917,7 +917,7 @@
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/internal_api.ListMasterLogsResponse"
"$ref": "#/definitions/internal_api.ListLogsResponse"
}
},
"500": {
@@ -985,7 +985,7 @@
"AdminAuth": []
}
],
"description": "Aggregate log stats with basic filtering",
"description": "Aggregate log stats with basic filtering. Use group_by param for grouped statistics (model/day/month). Without group_by returns LogStatsResponse; with group_by returns GroupedStatsResponse.",
"produces": [
"application/json"
],
@@ -1005,13 +1005,24 @@
"description": "unix seconds",
"name": "until",
"in": "query"
},
{
"enum": [
"model",
"day",
"month"
],
"type": "string",
"description": "group by dimension: model, day, month. Returns GroupedStatsResponse when specified.",
"name": "group_by",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"description": "Grouped stats (when group_by is specified)",
"schema": {
"$ref": "#/definitions/internal_api.LogStatsResponse"
"$ref": "#/definitions/internal_api.GroupedStatsResponse"
}
},
"500": {
@@ -4169,6 +4180,46 @@
}
}
},
"internal_api.GroupedStatsItem": {
"type": "object",
"properties": {
"avg_latency_ms": {
"type": "number"
},
"count": {
"type": "integer"
},
"date": {
"description": "For group_by=day",
"type": "string"
},
"model": {
"description": "For group_by=model",
"type": "string"
},
"month": {
"description": "For group_by=month",
"type": "string"
},
"tokens_in": {
"type": "integer"
},
"tokens_out": {
"type": "integer"
}
}
},
"internal_api.GroupedStatsResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/internal_api.GroupedStatsItem"
}
}
}
},
"internal_api.IssueChildKeyRequest": {
"type": "object",
"properties": {
@@ -4209,6 +4260,26 @@
}
}
},
"internal_api.ListLogsResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/internal_api.LogView"
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"total": {
"type": "integer"
}
}
},
"internal_api.ListMasterLogsResponse": {
"type": "object",
"properties": {
@@ -4253,6 +4324,65 @@
}
}
},
"internal_api.LogView": {
"type": "object",
"properties": {
"audit_reason": {
"type": "string"
},
"client_ip": {
"type": "string"
},
"created_at": {
"type": "integer"
},
"error_message": {
"type": "string"
},
"group": {
"type": "string"
},
"id": {
"type": "integer"
},
"key_id": {
"type": "integer"
},
"latency_ms": {
"type": "integer"
},
"model": {
"type": "string"
},
"provider_id": {
"type": "integer"
},
"provider_name": {
"type": "string"
},
"provider_type": {
"type": "string"
},
"request_body": {
"type": "string"
},
"request_size": {
"type": "integer"
},
"response_size": {
"type": "integer"
},
"status_code": {
"type": "integer"
},
"tokens_in": {
"type": "integer"
},
"tokens_out": {
"type": "integer"
}
}
},
"internal_api.ManageMasterRequest": {
"type": "object",
"required": [

101
docs/swagger.yaml
View File

@@ -417,6 +417,33 @@ definitions:
deleted_count:
type: integer
type: object
internal_api.GroupedStatsItem:
properties:
avg_latency_ms:
type: number
count:
type: integer
date:
description: For group_by=day
type: string
model:
description: For group_by=model
type: string
month:
description: For group_by=month
type: string
tokens_in:
type: integer
tokens_out:
type: integer
type: object
internal_api.GroupedStatsResponse:
properties:
items:
items:
$ref: '#/definitions/internal_api.GroupedStatsItem'
type: array
type: object
internal_api.IssueChildKeyRequest:
properties:
allow_ips:
@@ -443,6 +470,19 @@ definitions:
tokens:
type: integer
type: object
internal_api.ListLogsResponse:
properties:
items:
items:
$ref: '#/definitions/internal_api.LogView'
type: array
limit:
type: integer
offset:
type: integer
total:
type: integer
type: object
internal_api.ListMasterLogsResponse:
properties:
items:
@@ -472,6 +512,45 @@ definitions:
total:
type: integer
type: object
internal_api.LogView:
properties:
audit_reason:
type: string
client_ip:
type: string
created_at:
type: integer
error_message:
type: string
group:
type: string
id:
type: integer
key_id:
type: integer
latency_ms:
type: integer
model:
type: string
provider_id:
type: integer
provider_name:
type: string
provider_type:
type: string
request_body:
type: string
request_size:
type: integer
response_size:
type: integer
status_code:
type: integer
tokens_in:
type: integer
tokens_out:
type: integer
type: object
internal_api.ManageMasterRequest:
properties:
action:
@@ -1426,7 +1505,8 @@ paths:
tags:
- admin
get:
description: List request logs with basic filtering/pagination
description: List request logs with basic filtering/pagination. Returns full
log records including request_body.
parameters:
- description: limit (default 50, max 200)
in: query
@@ -1466,7 +1546,7 @@ paths:
"200":
description: OK
schema:
$ref: '#/definitions/internal_api.ListMasterLogsResponse'
$ref: '#/definitions/internal_api.ListLogsResponse'
"500":
description: Internal Server Error
schema:
@@ -1478,7 +1558,9 @@ paths:
- admin
/admin/logs/stats:
get:
description: Aggregate log stats with basic filtering
description: Aggregate log stats with basic filtering. Use group_by param for
grouped statistics (model/day/month). Without group_by returns LogStatsResponse;
with group_by returns GroupedStatsResponse.
parameters:
- description: unix seconds
in: query
@@ -1488,13 +1570,22 @@ paths:
in: query
name: until
type: integer
- description: 'group by dimension: model, day, month. Returns GroupedStatsResponse
when specified.'
enum:
- model
- day
- month
in: query
name: group_by
type: string
produces:
- application/json
responses:
"200":
description: OK
description: Grouped stats (when group_by is specified)
schema:
$ref: '#/definitions/internal_api.LogStatsResponse'
$ref: '#/definitions/internal_api.GroupedStatsResponse'
"500":
description: Internal Server Error
schema: