shishengliang/lingniu-vehicle-ingest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(go): document realtime total semantics

Browse Source
This commit is contained in:
lingniu
2026-07-03 07:53:30 +08:00
parent b3ea2bd91f
commit 0aa71402d1
2 changed files with 9 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
go/vehicle-gateway/internal/realtime/openapi.go
View File

@@ -44,7 +44,7 @@ func realtimeOpenAPISpec() map[string]any {
"/api/realtime/snapshots": map[string]any{
"get": map[string]any{
"summary": "查询车辆实时快照",
"description": "从 vehicle_realtime_snapshot 查询各协议最新在线快照，支持协议、VIN、车牌过滤和分页。",
"description": "从 vehicle_realtime_snapshot 查询各协议最新在线快照，支持协议、VIN、车牌过滤和分页。默认不执行 COUNT(*)，total 默认表示本页返回条数；需要精确总数时传 includeTotal=true。",
"tags": []string{"Realtime Snapshot API"},
"x-table": "vehicle_realtime_snapshot",
"parameters": commonRealtimeParameters(),
@@ -63,7 +63,7 @@ func realtimeOpenAPISpec() map[string]any {
"/api/realtime/locations": map[string]any{
"get": map[string]any{
"summary": "查询车辆实时位置",
"description": "从 vehicle_realtime_location 查询各协议最新位置，支持协议、VIN、车牌过滤和分页。",
"description": "从 vehicle_realtime_location 查询各协议最新位置，支持协议、VIN、车牌过滤和分页。默认不执行 COUNT(*)，total 默认表示本页返回条数；需要精确总数时传 includeTotal=true。",
"tags": []string{"Realtime Location API"},
"x-table": "vehicle_realtime_location",
"parameters": commonRealtimeParameters(),
@@ -127,6 +127,7 @@ func commonRealtimeParameters() []map[string]any {
{"name": "protocol", "in": "query", "schema": map[string]any{"type": "string", "enum": []string{"GB32960", "JT808", "YUTONG_MQTT"}}, "required": false},
{"name": "vin", "in": "query", "schema": map[string]any{"type": "string"}, "required": false},
{"name": "plate", "in": "query", "schema": map[string]any{"type": "string"}, "required": false},
{"name": "includeTotal", "in": "query", "schema": map[string]any{"type": "boolean", "default": false}, "required": false, "description": "默认 false，不执行 COUNT(*)；true 时返回精确总数。"},
{"name": "limit", "in": "query", "schema": map[string]any{"type": "integer", "minimum": 1, "maximum": 1000, "default": 50}, "required": false},
{"name": "offset", "in": "query", "schema": map[string]any{"type": "integer", "minimum": 0, "maximum": 1000000, "default": 0}, "required": false},
}
@@ -137,7 +138,7 @@ func pageSchema(itemRef string) map[string]any {
"type": "object",
"properties": map[string]any{
"items": map[string]any{"type": "array", "items": map[string]any{"$ref": itemRef}},
"total": integerSchema(1),
"total": map[string]any{"type": "integer", "example": 1, "description": "默认表示本页返回条数；includeTotal=true 时表示精确总数。"},
"limit": integerSchema(50),
"offset": integerSchema(0),
},

5
go/vehicle-gateway/internal/realtime/openapi_test.go
View File

@@ -22,4 +22,9 @@ func TestOpenAPIHandlerDocumentsRealtimeSnapshotAndLocation(t *testing.T) {
t.Fatalf("openapi missing %s: %s", want, body)
}
}
for _, want := range []string{`"includeTotal"`, `默认不执行 COUNT(*)`, `total 默认表示本页返回条数`} {
if !strings.Contains(body, want) {
t.Fatalf("openapi should document lightweight total semantics, missing %s: %s", want, body)
}
}
}