mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-09-16 23:27:14 +00:00
docs(api): align OpenAPI with runtime contracts (#6409)
Document the cookie-authenticated WebSocket upgrade and its emitted envelopes without exporting pseudo-paths. Align REST response schemas, paged-client filters, and subscription HEAD operations with their runtime implementations, then regenerate frontend and docs artifacts.
This commit is contained in:
Gleb Gudkov
@@ -1245,6 +1245,56 @@ export const SCHEMAS: Record<string, unknown> = {
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"ClientPageResponse": {
|
||||
"description": "ClientPageResponse is the shape returned by ListPaged. `Total` is the\nrow count in the DB; `Filtered` is the count after Search/Filter/Protocol\nwere applied, before pagination. The page contains at most PageSize items.\nSummary is computed across the full DB row set so dashboard counters\non the clients page stay stable as the user paginates/filters.",
|
||||
"properties": {
|
||||
"filtered": {
|
||||
"example": 47,
|
||||
"type": "integer"
|
||||
},
|
||||
"groups": {
|
||||
"example": [
|
||||
"staff",
|
||||
"trial"
|
||||
],
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"items": {
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/ClientSlim"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"page": {
|
||||
"example": 1,
|
||||
"type": "integer"
|
||||
},
|
||||
"pageSize": {
|
||||
"example": 25,
|
||||
"type": "integer"
|
||||
},
|
||||
"summary": {
|
||||
"$ref": "#/components/schemas/ClientsSummary"
|
||||
},
|
||||
"total": {
|
||||
"example": 2000,
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"filtered",
|
||||
"groups",
|
||||
"items",
|
||||
"page",
|
||||
"pageSize",
|
||||
"summary",
|
||||
"total"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"ClientRecord": {
|
||||
"properties": {
|
||||
"adTag": {
|
||||
@@ -1394,6 +1444,105 @@ export const SCHEMAS: Record<string, unknown> = {
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"ClientSlim": {
|
||||
"description": "ClientSlim is the row-shape used by the clients page. It drops fields the\ntable never reads (UUID, password, auth, flow, security, reverse, tgId)\nso the list payload stays compact even when the panel manages thousands\nof clients. Modals that need the full record still call /get/:email.",
|
||||
"properties": {
|
||||
"comment": {
|
||||
"example": "Primary device",
|
||||
"type": "string"
|
||||
},
|
||||
"createdAt": {
|
||||
"example": 1735000000000,
|
||||
"format": "int64",
|
||||
"type": "integer"
|
||||
},
|
||||
"email": {
|
||||
"example": "alice@example.com",
|
||||
"type": "string"
|
||||
},
|
||||
"enable": {
|
||||
"example": true,
|
||||
"type": "boolean"
|
||||
},
|
||||
"expiryTime": {
|
||||
"example": 1735689600000,
|
||||
"format": "int64",
|
||||
"type": "integer"
|
||||
},
|
||||
"group": {
|
||||
"example": "staff",
|
||||
"type": "string"
|
||||
},
|
||||
"inboundIds": {
|
||||
"example": [
|
||||
3,
|
||||
5
|
||||
],
|
||||
"items": {
|
||||
"type": "integer"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"limitHwid": {
|
||||
"example": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"limitIp": {
|
||||
"example": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"reset": {
|
||||
"example": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"resetDay": {
|
||||
"example": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"resetMax": {
|
||||
"example": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"subId": {
|
||||
"example": "abcd1234",
|
||||
"type": "string"
|
||||
},
|
||||
"totalGB": {
|
||||
"example": 53687091200,
|
||||
"format": "int64",
|
||||
"type": "integer"
|
||||
},
|
||||
"traffic": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/ClientTraffic"
|
||||
}
|
||||
],
|
||||
"nullable": true
|
||||
},
|
||||
"updatedAt": {
|
||||
"example": 1735100000000,
|
||||
"format": "int64",
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"createdAt",
|
||||
"email",
|
||||
"enable",
|
||||
"expiryTime",
|
||||
"inboundIds",
|
||||
"limitHwid",
|
||||
"limitIp",
|
||||
"reset",
|
||||
"resetDay",
|
||||
"resetMax",
|
||||
"subId",
|
||||
"totalGB",
|
||||
"updatedAt"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"ClientTraffic": {
|
||||
"description": "ClientTraffic represents traffic statistics and limits for a specific client.\nIt tracks upload/download usage, expiry times, and online status for inbound clients.",
|
||||
"properties": {
|
||||
@@ -1491,6 +1640,80 @@ export const SCHEMAS: Record<string, unknown> = {
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"ClientsSummary": {
|
||||
"description": "ClientsSummary collects per-bucket counts plus the matching email lists so\nthe clients page can render the dashboard stat cards and their hover\npopovers without shipping the full client array. The counters are exact;\nthe lists stop at clientSummaryEmailCap entries and only back the popovers.",
|
||||
"properties": {
|
||||
"active": {
|
||||
"example": 1850,
|
||||
"type": "integer"
|
||||
},
|
||||
"deactive": {
|
||||
"example": [
|
||||
"bob@example.com"
|
||||
],
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"deactiveCount": {
|
||||
"example": 150,
|
||||
"type": "integer"
|
||||
},
|
||||
"depleted": {
|
||||
"example": [],
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"depletedCount": {
|
||||
"example": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"expiring": {
|
||||
"example": [],
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"expiringCount": {
|
||||
"example": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"online": {
|
||||
"example": [
|
||||
"alice@example.com"
|
||||
],
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"onlineCount": {
|
||||
"example": 1,
|
||||
"type": "integer"
|
||||
},
|
||||
"total": {
|
||||
"example": 2000,
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"active",
|
||||
"deactive",
|
||||
"deactiveCount",
|
||||
"depleted",
|
||||
"depletedCount",
|
||||
"expiring",
|
||||
"expiringCount",
|
||||
"online",
|
||||
"onlineCount",
|
||||
"total"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"FallbackParentInfo": {
|
||||
"description": "FallbackParentInfo carries everything the frontend needs to rewrite a\nchild inbound's client link: where to connect (the master's address\nand port) and which path matched on the master's fallbacks array.\nThe frontend already has the master inbound in its dbInbounds list,\nso we only ship identifiers + the match path here.",
|
||||
"properties": {
|
||||
@@ -2337,6 +2560,118 @@ export const SCHEMAS: Record<string, unknown> = {
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"InboundTrafficSummary": {
|
||||
"properties": {
|
||||
"down": {
|
||||
"example": 2097152,
|
||||
"format": "int64",
|
||||
"type": "integer"
|
||||
},
|
||||
"enable": {
|
||||
"example": true,
|
||||
"type": "boolean"
|
||||
},
|
||||
"id": {
|
||||
"example": 1,
|
||||
"type": "integer"
|
||||
},
|
||||
"total": {
|
||||
"example": 10737418240,
|
||||
"format": "int64",
|
||||
"type": "integer"
|
||||
},
|
||||
"up": {
|
||||
"example": 1048576,
|
||||
"format": "int64",
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"down",
|
||||
"enable",
|
||||
"id",
|
||||
"total",
|
||||
"up"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"LogEntry": {
|
||||
"properties": {
|
||||
"DateTime": {
|
||||
"example": "2025-01-01T12:00:00Z",
|
||||
"format": "date-time",
|
||||
"type": "string"
|
||||
},
|
||||
"Email": {
|
||||
"example": "alice@example.com",
|
||||
"type": "string"
|
||||
},
|
||||
"Event": {
|
||||
"example": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"FromAddress": {
|
||||
"example": "192.0.2.10:54321",
|
||||
"type": "string"
|
||||
},
|
||||
"Inbound": {
|
||||
"example": "inbound-443",
|
||||
"type": "string"
|
||||
},
|
||||
"Outbound": {
|
||||
"example": "direct",
|
||||
"type": "string"
|
||||
},
|
||||
"ToAddress": {
|
||||
"example": "example.com:443",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"DateTime",
|
||||
"Email",
|
||||
"Event",
|
||||
"FromAddress",
|
||||
"Inbound",
|
||||
"Outbound",
|
||||
"ToAddress"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"MLDSA65Response": {
|
||||
"properties": {
|
||||
"seed": {
|
||||
"example": "mldsa65-seed",
|
||||
"type": "string"
|
||||
},
|
||||
"verify": {
|
||||
"example": "mldsa65-verify",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"seed",
|
||||
"verify"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"MLKEM768Response": {
|
||||
"properties": {
|
||||
"client": {
|
||||
"example": "mlkem768-client",
|
||||
"type": "string"
|
||||
},
|
||||
"seed": {
|
||||
"example": "mlkem768-seed",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"client",
|
||||
"seed"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Msg": {
|
||||
"properties": {
|
||||
"msg": {
|
||||
@@ -2354,6 +2689,18 @@ export const SCHEMAS: Record<string, unknown> = {
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"NewUUIDResponse": {
|
||||
"properties": {
|
||||
"uuid": {
|
||||
"example": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"uuid"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Node": {
|
||||
"description": "Node represents a remote 3x-ui panel registered with the central panel.\nThe central panel polls each node's existing /panel/api/server/status\nendpoint over HTTP using the per-node ApiToken to populate the runtime\nstatus fields below.",
|
||||
"properties": {
|
||||
@@ -3409,6 +3756,41 @@ export const SCHEMAS: Record<string, unknown> = {
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Traffic": {
|
||||
"description": "Traffic represents network traffic statistics for Xray connections.\nIt tracks upload and download bytes for inbound or outbound traffic.",
|
||||
"properties": {
|
||||
"Down": {
|
||||
"example": 2097152,
|
||||
"format": "int64",
|
||||
"type": "integer"
|
||||
},
|
||||
"IsInbound": {
|
||||
"example": true,
|
||||
"type": "boolean"
|
||||
},
|
||||
"IsOutbound": {
|
||||
"example": false,
|
||||
"type": "boolean"
|
||||
},
|
||||
"Tag": {
|
||||
"example": "inbound-443",
|
||||
"type": "string"
|
||||
},
|
||||
"Up": {
|
||||
"example": 1048576,
|
||||
"format": "int64",
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"Down",
|
||||
"IsInbound",
|
||||
"IsOutbound",
|
||||
"Tag",
|
||||
"Up"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"User": {
|
||||
"description": "User represents a user account in the 3x-ui panel.",
|
||||
"properties": {
|
||||
|
||||
Reference in New Issue
Block a user