系统API注解和swagger访问

This commit is contained in:
xz2000 2025-07-23 17:09:33 +08:00
parent 9d7dcae1c8
commit 54f3fc6f61

View File

@ -41,14 +41,14 @@
"schema": {
"type": "object",
"properties": {
"status": {"type": "string"},
"status": {"type": "string", "example": "success"},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product_id": {"type": "string"},
"product_name": {"type": "string"}
"product_id": {"type": "string", "example": "P001"},
"product_name": {"type": "string", "example": "产品A"}
}
}
}
@ -76,7 +76,34 @@
}
],
"responses": {
"200": {"description": "成功获取产品详情"},
"200": {
"description": "成功获取产品详情",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "object",
"properties": {
"product_id": {"type": "string", "example": "P001"},
"product_name": {"type": "string", "example": "产品A"},
"data_points": {"type": "integer", "example": 365},
"date_range": {
"type": "object",
"properties": {
"start": {"type": "string", "example": "2023-01-01"},
"end": {"type": "string", "example": "2023-12-31"}
}
}
}
}
}
}
}
}
},
"404": {"description": "产品不存在"},
"500": {"description": "服务器内部错误"}
}
@ -109,7 +136,29 @@
}
],
"responses": {
"200": {"description": "成功获取销售数据"},
"200": {
"description": "成功获取销售数据",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {"type": "string", "example": "2023-12-01"},
"sales": {"type": "integer", "example": 150}
}
}
}
}
}
}
}
},
"404": {"description": "产品不存在"},
"500": {"description": "服务器内部错误"}
}
@ -136,7 +185,27 @@
}
},
"responses": {
"200": {"description": "数据上传成功"},
"200": {
"description": "数据上传成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"message": {"type": "string", "example": "数据上传成功"},
"data": {
"type": "object",
"properties": {
"products": {"type": "integer", "example": 10},
"rows": {"type": "integer", "example": 3650}
}
}
}
}
}
}
},
"400": {"description": "请求错误"},
"500": {"description": "服务器内部错误"}
}
@ -148,7 +217,35 @@
"summary": "获取所有训练任务列表",
"description": "返回所有正在进行、已完成或失败的训练任务",
"responses": {
"200": {"description": "成功获取任务列表"}
"200": {
"description": "成功获取任务列表",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"task_id": {"type": "string", "example": "uuid-1234"},
"product_id": {"type": "string", "example": "P001"},
"model_type": {"type": "string", "example": "mlstm"},
"status": {"type": "string", "example": "completed"},
"start_time": {"type": "string", "example": "2023-12-25T10:00:00Z"},
"metrics": {"type": "object", "example": {"R2": 0.95, "RMSE": 5.5}},
"error": {"type": "string", "nullable": true},
"model_path": {"type": "string", "example": "/path/to/model.pth"}
}
}
}
}
}
}
}
}
}
},
"post": {
@ -173,7 +270,20 @@
}
},
"responses": {
"200": {"description": "训练任务已启动"},
"200": {
"description": "训练任务已启动",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {"type": "string", "example": "模型训练已开始"},
"task_id": {"type": "string", "example": "new-uuid-5678"}
}
}
}
}
},
"400": {"description": "请求错误"}
}
}
@ -193,7 +303,29 @@
}
],
"responses": {
"200": {"description": "成功获取任务状态"},
"200": {
"description": "成功获取任务状态",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "object",
"properties": {
"product_id": {"type": "string", "example": "P001"},
"model_type": {"type": "string", "example": "mlstm"},
"status": {"type": "string", "example": "running"},
"progress": {"type": "number", "example": 50.5},
"created_at": {"type": "string", "example": "2023-12-25T10:00:00Z"}
}
}
}
}
}
}
},
"404": {"description": "任务不存在"},
"500": {"description": "服务器内部错误"}
}
@ -225,7 +357,38 @@
}
},
"responses": {
"200": {"description": "预测成功"},
"200": {
"description": "预测成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "object",
"properties": {
"product_id": {"type": "string", "example": "P001"},
"product_name": {"type": "string", "example": "产品A"},
"model_type": {"type": "string", "example": "mlstm"},
"predictions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {"type": "string", "example": "2024-01-01"},
"predicted_sales": {"type": "integer", "example": 100}
}
}
},
"visualization": {"type": "string", "example": "base64-encoded-image-string"}
}
}
}
}
}
}
},
"400": {"description": "请求错误"},
"404": {"description": "产品或模型不存在"},
"500": {"description": "服务器内部错误"}
@ -255,7 +418,37 @@
}
},
"responses": {
"200": {"description": "比较成功"},
"200": {
"description": "比较成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "object",
"properties": {
"product_id": {"type": "string", "example": "P001"},
"comparison": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {"type": "string", "example": "2024-01-01"},
"mlstm": {"type": "integer", "example": 100},
"transformer": {"type": "integer", "example": 102}
}
}
},
"visualization": {"type": "string", "example": "base64-encoded-image-string"}
}
}
}
}
}
}
},
"400": {"description": "请求错误"},
"404": {"description": "产品或模型不存在"},
"500": {"description": "服务器内部错误"}
@ -267,7 +460,31 @@
"tags": ["模型预测"],
"summary": "获取历史预测记录",
"responses": {
"200": {"description": "获取成功"}
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"prediction_id": {"type": "string", "example": "pred-uuid-1"},
"product_id": {"type": "string", "example": "P001"},
"model_type": {"type": "string", "example": "mlstm"},
"created_at": {"type": "string", "example": "2023-12-20T11:00:00Z"}
}
}
}
}
}
}
}
}
}
}
},
@ -284,7 +501,38 @@
}
],
"responses": {
"200": {"description": "获取成功"},
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "object",
"properties": {
"prediction_id": {"type": "string", "example": "pred-uuid-1"},
"product_id": {"type": "string", "example": "P001"},
"model_type": {"type": "string", "example": "mlstm"},
"predictions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {"type": "string", "example": "2023-12-21"},
"predicted_sales": {"type": "integer", "example": 110}
}
}
},
"analysis": {"type": "object", "example": {"trend": "upward"}}
}
}
}
}
}
}
},
"404": {"description": "记录不存在"}
}
},
@ -300,7 +548,20 @@
}
],
"responses": {
"200": {"description": "删除成功"},
"200": {
"description": "删除成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"message": {"type": "string", "example": "预测记录已删除"}
}
}
}
}
},
"404": {"description": "记录不存在"}
}
}
@ -314,7 +575,32 @@
{"name": "model_type", "in": "query", "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "获取成功"}
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"model_id": {"type": "string", "example": "P001_mlstm_v1"},
"product_id": {"type": "string", "example": "P001"},
"model_type": {"type": "string", "example": "mlstm"},
"version": {"type": "string", "example": "v1"},
"created_at": {"type": "string", "example": "2023-12-15T09:00:00Z"}
}
}
}
}
}
}
}
}
}
}
},
@ -326,7 +612,29 @@
{"name": "model_id", "in": "path", "required": true, "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "获取成功"},
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "object",
"properties": {
"model_id": {"type": "string", "example": "P001_mlstm_v1"},
"product_id": {"type": "string", "example": "P001"},
"model_type": {"type": "string", "example": "mlstm"},
"version": {"type": "string", "example": "v1"},
"metrics": {"type": "object", "example": {"R2": 0.95, "RMSE": 5.5}}
}
}
}
}
}
}
},
"404": {"description": "模型不存在"}
}
},
@ -337,7 +645,20 @@
{"name": "model_id", "in": "path", "required": true, "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "删除成功"},
"200": {
"description": "删除成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"message": {"type": "string", "example": "模型已删除"}
}
}
}
}
},
"404": {"description": "模型不存在"}
}
}
@ -360,7 +681,29 @@
"tags": ["模型管理"],
"summary": "获取系统支持的所有模型类型",
"responses": {
"200": {"description": "获取成功"}
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {"type": "string", "example": "mlstm"},
"name": {"type": "string", "example": "mLSTM"}
}
}
}
}
}
}
}
}
}
}
},
@ -373,7 +716,28 @@
{"name": "model_type", "in": "path", "required": true, "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "获取成功"}
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "object",
"properties": {
"product_id": {"type": "string", "example": "P001"},
"model_type": {"type": "string", "example": "mlstm"},
"versions": {"type": "array", "items": {"type": "string"}, "example": ["v1", "v2"]},
"latest_version": {"type": "string", "example": "v2"}
}
}
}
}
}
}
}
}
}
},
@ -382,14 +746,56 @@
"tags": ["数据管理"],
"summary": "获取所有店铺列表",
"responses": {
"200": {"description": "获取成功"}
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"store_id": {"type": "string", "example": "S001"},
"store_name": {"type": "string", "example": "第一分店"}
}
}
},
"count": {"type": "integer", "example": 2}
}
}
}
}
}
}
},
"post": {
"tags": ["数据管理"],
"summary": "创建新店铺",
"responses": {
"200": {"description": "创建成功"}
"200": {
"description": "创建成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"message": {"type": "string", "example": "店铺创建成功"},
"data": {
"type": "object",
"properties": {
"store_id": {"type": "string", "example": "S003"}
}
}
}
}
}
}
}
}
}
},
@ -401,7 +807,31 @@
{"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "获取成功"},
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "object",
"properties": {
"store_id": {"type": "string", "example": "S001"},
"store_name": {"type": "string", "example": "第一分店"},
"location": {"type": "string", "example": "市中心"},
"size": {"type": "number", "example": 120.5},
"type": {"type": "string", "example": "旗舰店"},
"opening_date": {"type": "string", "example": "2022-01-01"},
"status": {"type": "string", "example": "active"}
}
}
}
}
}
}
},
"404": {"description": "店铺不存在"}
}
},
@ -412,7 +842,20 @@
{"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "更新成功"},
"200": {
"description": "更新成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"message": {"type": "string", "example": "店铺更新成功"}
}
}
}
}
},
"404": {"description": "店铺不存在"}
}
},
@ -423,7 +866,20 @@
{"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "删除成功"},
"200": {
"description": "删除成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"message": {"type": "string", "example": "店铺删除成功"}
}
}
}
}
},
"404": {"description": "店铺不存在"}
}
}
@ -436,7 +892,30 @@
{"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "获取成功"}
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product_id": {"type": "string", "example": "P001"},
"product_name": {"type": "string", "example": "产品A"}
}
}
},
"count": {"type": "integer", "example": 1}
}
}
}
}
}
}
}
},
@ -448,7 +927,27 @@
{"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
],
"responses": {
"200": {"description": "获取成功"}
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "object",
"properties": {
"total_sales": {"type": "number", "example": 150000.0},
"total_quantity": {"type": "integer", "example": 7500},
"products_count": {"type": "integer", "example": 50}
}
}
}
}
}
}
}
}
}
},
@ -457,7 +956,35 @@
"tags": ["数据管理"],
"summary": "获取销售数据列表",
"responses": {
"200": {"description": "获取成功"}
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {"type": "string", "example": "success"},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {"type": "string", "example": "2023-12-01"},
"store_id": {"type": "string", "example": "S001"},
"product_id": {"type": "string", "example": "P001"},
"sales": {"type": "integer", "example": 150},
"price": {"type": "number", "example": 25.5}
}
}
},
"total": {"type": "integer", "example": 100},
"page": {"type": "integer", "example": 1},
"page_size": {"type": "integer", "example": 1}
}
}
}
}
}
}
}
}