From 458f7afdbfac50f53f79ed69474c70e7df9b28c7 Mon Sep 17 00:00:00 2001 From: douxu Date: Mon, 20 Oct 2025 17:30:55 +0800 Subject: [PATCH] optimize doc of measurement recommend api --- docs/docs.go | 49 ++++++++++++++++++-------------- docs/swagger.json | 49 ++++++++++++++++++-------------- docs/swagger.yaml | 33 ++++++++++----------- handler/measurement_recommend.go | 43 +++++++++++++++++++++------- network/response.go | 17 +++++------ 5 files changed, 115 insertions(+), 76 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 73df182..5e2be9a 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -23,8 +23,8 @@ const docTemplate = `{ "host": "{{.Host}}", "basePath": "{{.BasePath}}", "paths": { - "/api/v1/recommend/measurement": { - "post": { + "/measurement/recommend": { + "get": { "description": "根据用户输入的字符串，从 Redis 中查询可能的测量点或结构路径，并提供推荐列表。", "consumes": [ "application/json" @@ -33,12 +33,12 @@ const docTemplate = `{ "application/json" ], "tags": [ - "Recommend" + "Measurement Recommend" ], "summary": "测量点推荐（搜索框自动补全）", "parameters": [ { - "description": "查询输入参数，例如 'trans' 或 'grid_key.'", + "description": "查询输入参数，例如 'trans' 或 'transformfeeder1_220.'", "name": "request", "in": "body", "required": true, @@ -49,7 +49,25 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "请求或查询失败。**注意**：HTTP 状态码始终为 200，但内部 Code 为 400 (参数错误) 或 500 (内部错误)。", + "description": "返回推荐列表成功", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/network.SuccessResponse" + }, + { + "type": "object", + "properties": { + "payload": { + "$ref": "#/definitions/network.MeasurementRecommendPayload" + } + } + } + ] + } + }, + "400": { + "description": "返回推荐列表失败", "schema": { "$ref": "#/definitions/network.FailureResponse" } @@ -109,13 +127,7 @@ const docTemplate = `{ "example": "failed to get recommend data from redis" }, "payload": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "example": { - "key": "value" - } + "type": "object" } } }, @@ -128,7 +140,7 @@ const docTemplate = `{ }, "offset": { "type": "integer", - "example": 20 + "example": 21 }, "recommended_list": { "type": "array", @@ -137,7 +149,8 @@ const docTemplate = `{ }, "example": [ "[\"I_A_rms\"", - " \"I_B_rms\"]" + " \"I_B_rms\"", + "\"I_C_rms\"]" ] } } @@ -163,13 +176,7 @@ const docTemplate = `{ "example": "success" }, "payload": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "example": { - "key": "value" - } + "type": "object" } } } diff --git a/docs/swagger.json b/docs/swagger.json index 8ca1c0f..d638ab4 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -17,8 +17,8 @@ "host": "localhost:8080", "basePath": "/api/v1", "paths": { - "/api/v1/recommend/measurement": { - "post": { + "/measurement/recommend": { + "get": { "description": "根据用户输入的字符串，从 Redis 中查询可能的测量点或结构路径，并提供推荐列表。", "consumes": [ "application/json" @@ -27,12 +27,12 @@ "application/json" ], "tags": [ - "Recommend" + "Measurement Recommend" ], "summary": "测量点推荐（搜索框自动补全）", "parameters": [ { - "description": "查询输入参数，例如 'trans' 或 'grid_key.'", + "description": "查询输入参数，例如 'trans' 或 'transformfeeder1_220.'", "name": "request", "in": "body", "required": true, @@ -43,7 +43,25 @@ ], "responses": { "200": { - "description": "请求或查询失败。**注意**：HTTP 状态码始终为 200，但内部 Code 为 400 (参数错误) 或 500 (内部错误)。", + "description": "返回推荐列表成功", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/network.SuccessResponse" + }, + { + "type": "object", + "properties": { + "payload": { + "$ref": "#/definitions/network.MeasurementRecommendPayload" + } + } + } + ] + } + }, + "400": { + "description": "返回推荐列表失败", "schema": { "$ref": "#/definitions/network.FailureResponse" } @@ -103,13 +121,7 @@ "example": "failed to get recommend data from redis" }, "payload": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "example": { - "key": "value" - } + "type": "object" } } }, @@ -122,7 +134,7 @@ }, "offset": { "type": "integer", - "example": 20 + "example": 21 }, "recommended_list": { "type": "array", @@ -131,7 +143,8 @@ }, "example": [ "[\"I_A_rms\"", - " \"I_B_rms\"]" + " \"I_B_rms\"", + "\"I_C_rms\"]" ] } } @@ -157,13 +170,7 @@ "example": "success" }, "payload": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "example": { - "key": "value" - } + "type": "object" } } } diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 25cbe3c..a9bd578 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -9,10 +9,6 @@ definitions: example: failed to get recommend data from redis type: string payload: - additionalProperties: - type: string - example: - key: value type: object type: object network.MeasurementRecommendPayload: @@ -21,12 +17,13 @@ definitions: example: transformfeeder1_220. type: string offset: - example: 20 + example: 21 type: integer recommended_list: example: - '["I_A_rms"' - - ' "I_B_rms"]' + - ' "I_B_rms"' + - '"I_C_rms"]' items: type: string type: array @@ -46,10 +43,6 @@ definitions: example: success type: string payload: - additionalProperties: - type: string - example: - key: value type: object type: object host: localhost:8080 @@ -65,13 +58,13 @@ info: title: ModelRT 实时模型服务 API 文档 version: "1.0" paths: - /api/v1/recommend/measurement: - post: + /measurement/recommend: + get: consumes: - application/json description: 根据用户输入的字符串，从 Redis 中查询可能的测量点或结构路径，并提供推荐列表。 parameters: - - description: 查询输入参数，例如 'trans' 或 'grid_key.' + - description: 查询输入参数，例如 'trans' 或 'transformfeeder1_220.' in: body name: request required: true @@ -81,13 +74,21 @@ paths: - application/json responses: "200": - description: 请求或查询失败。**注意**：HTTP 状态码始终为 200，但内部 Code 为 400 (参数错误) 或 500 - (内部错误)。 + description: 返回推荐列表成功 + schema: + allOf: + - $ref: '#/definitions/network.SuccessResponse' + - properties: + payload: + $ref: '#/definitions/network.MeasurementRecommendPayload' + type: object + "400": + description: 返回推荐列表失败 schema: $ref: '#/definitions/network.FailureResponse' summary: 测量点推荐（搜索框自动补全） tags: - - Recommend + - Measurement Recommend /model/diagram_load/{page_id}: get: consumes: diff --git a/handler/measurement_recommend.go b/handler/measurement_recommend.go index c9cf038..debafa6 100644 --- a/handler/measurement_recommend.go +++ b/handler/measurement_recommend.go @@ -11,17 +11,35 @@ import ( "github.com/gin-gonic/gin" ) -// MeasurementRecommendHandler define measurement recommend API // MeasurementRecommendHandler define measurement recommend API // @Summary 测量点推荐（搜索框自动补全） // @Description 根据用户输入的字符串，从 Redis 中查询可能的测量点或结构路径，并提供推荐列表。 -// @Tags Recommend +// @Tags Measurement Recommend // @Accept json // @Produce json -// @Param request body network.MeasurementRecommendRequest true "查询输入参数，例如 'trans' 或 'grid_key.'" -// @Success 200 {object} network.SuccessResponse{payload=network.MeasurementRecommendPayload} "成功返回推荐列表" -// @Failure 200 {object} network.FailureResponse "请求或查询失败。**注意**：HTTP 状态码始终为 200，但内部 Code 为 400 (参数错误) 或 500 (内部错误)。" -// @Router /api/v1/recommend/measurement [post] +// @Param request body network.MeasurementRecommendRequest true "查询输入参数，例如 'trans' 或 'transformfeeder1_220.'" +// @Success 200 {object} network.SuccessResponse{payload=network.MeasurementRecommendPayload} "返回推荐列表成功" +// +// @Example 200 { +// "code": 200, +// "msg": "success", +// "payload": { +// "input": "transformfeeder1_220.", +// "offset": 21, +// "recommended_list": [ +// "I_A_rms", +// "I_B_rms", +// "I_C_rms", +// ] +// } +// } +// +// @Failure 400 {object} network.FailureResponse "返回推荐列表失败" +// @Example 400 { +// "code": 400, +// "msg": "failed to get recommend data from redis", +// } +// @Router /measurement/recommend [get] func MeasurementRecommendHandler(c *gin.Context) { var request network.MeasurementRecommendRequest @@ -84,10 +102,15 @@ func MeasurementRecommendHandler(c *gin.Context) { c.JSON(http.StatusOK, network.SuccessResponse{ Code: http.StatusOK, Msg: "success", - PayLoad: map[string]any{ - "input": request.Input, - "offset": finalOffset, - "recommended_list": resultRecommends, + // PayLoad: map[string]any{ + // "input": request.Input, + // "offset": finalOffset, + // "recommended_list": resultRecommends, + // }, + PayLoad: &network.MeasurementRecommendPayload{ + Input: request.Input, + Offset: finalOffset, + RecommendedList: resultRecommends, }, }) } diff --git a/network/response.go b/network/response.go index 6fe73e8..aeaad18 100644 --- a/network/response.go +++ b/network/response.go @@ -3,21 +3,22 @@ package network // FailureResponse define struct of standard failure API response format type FailureResponse struct { - Code int `json:"code" example:"500"` - Msg string `json:"msg" example:"failed to get recommend data from redis"` - PayLoad map[string]interface{} `json:"payload" swaggertype:"object,string" example:"key:value"` + Code int `json:"code" example:"500"` + Msg string `json:"msg" example:"failed to get recommend data from redis"` + PayLoad any `json:"payload" swaggertype:"object"` } // SuccessResponse define struct of standard successful API response format type SuccessResponse struct { - Code int `json:"code" example:"200"` - Msg string `json:"msg" example:"success"` - PayLoad map[string]interface{} `json:"payload" swaggertype:"object,string" example:"key:value"` + Code int `json:"code" example:"200"` + Msg string `json:"msg" example:"success"` + PayLoad any `json:"payload" swaggertype:"object"` } // MeasurementRecommendPayload define struct of represents the data payload for the successful recommendation response. type MeasurementRecommendPayload struct { Input string `json:"input" example:"transformfeeder1_220."` - Offset int `json:"offset" example:"20"` - RecommendedList []string `json:"recommended_list" example:"[\"I_A_rms\", \"I_B_rms\"]"` + Offset int `json:"offset" example:"21"` + RecommendedList []string `json:"recommended_list" example:"[\"I_A_rms\", \"I_B_rms\",\"I_C_rms\"]"` + // RecommendedList []string `json:"recommended_list"` }