465 lines
14 KiB
JSON
465 lines
14 KiB
JSON
{
|
|
"openapi": "3.0.0",
|
|
"info": {
|
|
"title": "化工商品分类树API",
|
|
"description": "提供SMM和Mysteel化工商品数据的分类树状结构API接口。\n\n## 功能特点\n- 树状数据在服务启动时加载到内存,响应速度快\n- 支持获取完整分类树或按路径查询特定节点\n- SMM数据: 127,509个指标, 最大深度8层\n- Mysteel数据: 272,450个指标, 最大深度10层\n\n## 数据结构\n每个树节点包含:\n- name: 节点名称\n- path: 完整路径(用|分隔)\n- level: 层级深度\n- children: 子节点数组\n- metrics: 该节点下的指标列表(仅叶子节点)\n",
|
|
"version": "1.0.0",
|
|
"contact": {
|
|
"name": "API Support"
|
|
}
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "http://localhost:18827",
|
|
"description": "本地开发服务器"
|
|
},
|
|
{
|
|
"url": "http://222.128.1.157:18827",
|
|
"description": "生产服务器"
|
|
}
|
|
],
|
|
"tags": [
|
|
{
|
|
"name": "分类树",
|
|
"description": "分类树状结构相关接口"
|
|
}
|
|
],
|
|
"paths": {
|
|
"/api/category-tree": {
|
|
"get": {
|
|
"tags": [
|
|
"分类树"
|
|
],
|
|
"summary": "获取完整分类树",
|
|
"description": "获取指定数据源的完整分类树状结构。\n\n## 使用场景\n- 前端树形组件初始化\n- 构建完整的分类导航\n- 级联选择器数据源\n\n## 注意事项\n- SMM树约53MB,Mysteel树约152MB\n- 建议前端实现懒加载或缓存策略\n- 响应时间取决于网络带宽\n",
|
|
"operationId": "getCategoryTree",
|
|
"parameters": [
|
|
{
|
|
"name": "source",
|
|
"in": "query",
|
|
"description": "数据源类型",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"SMM",
|
|
"Mysteel"
|
|
]
|
|
},
|
|
"example": "SMM"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "成功返回分类树",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CategoryTreeResponse"
|
|
},
|
|
"examples": {
|
|
"SMM示例": {
|
|
"value": {
|
|
"source": "SMM",
|
|
"total_metrics": 127509,
|
|
"tree": [
|
|
{
|
|
"name": "农业食品农资",
|
|
"path": "农业食品农资",
|
|
"level": 1,
|
|
"children": [
|
|
{
|
|
"name": "饲料",
|
|
"path": "农业食品农资|饲料",
|
|
"level": 2,
|
|
"children": [],
|
|
"metrics": []
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"Mysteel示例": {
|
|
"value": {
|
|
"source": "Mysteel",
|
|
"total_metrics": 272450,
|
|
"tree": [
|
|
{
|
|
"name": "钢铁产业",
|
|
"path": "钢铁产业",
|
|
"level": 1,
|
|
"children": []
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "未找到指定数据源",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
},
|
|
"example": {
|
|
"detail": "未找到数据源 'XXX' 的树状数据。可用数据源: SMM, Mysteel"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "服务器内部错误",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/category-tree/node": {
|
|
"get": {
|
|
"tags": [
|
|
"分类树"
|
|
],
|
|
"summary": "获取特定节点及其子树",
|
|
"description": "根据路径获取树中的特定节点及其所有子节点。\n\n## 使用场景\n- 懒加载:用户点击节点时动态加载子节点\n- 子树查询:获取某个分类下的所有数据\n- 面包屑导航:根据路径定位节点\n\n## 路径格式\n使用竖线(|)分隔层级,例如:\n- 一级: \"钴\"\n- 二级: \"钴|钴化合物\"\n- 三级: \"钴|钴化合物|硫酸钴\"\n",
|
|
"operationId": "getCategoryTreeNode",
|
|
"parameters": [
|
|
{
|
|
"name": "path",
|
|
"in": "query",
|
|
"description": "节点完整路径,用竖线(|)分隔",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"example": "钴|钴化合物|硫酸钴"
|
|
},
|
|
{
|
|
"name": "source",
|
|
"in": "query",
|
|
"description": "数据源类型",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"SMM",
|
|
"Mysteel"
|
|
]
|
|
},
|
|
"example": "SMM"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "成功返回节点数据",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/TreeNode"
|
|
},
|
|
"example": {
|
|
"name": "硫酸钴",
|
|
"path": "钴|钴化合物|硫酸钴",
|
|
"level": 3,
|
|
"children": [
|
|
{
|
|
"name": "产量",
|
|
"path": "钴|钴化合物|硫酸钴|产量",
|
|
"level": 4,
|
|
"children": [],
|
|
"metrics": [
|
|
{
|
|
"metric_id": "12345",
|
|
"metric_name": "SMM中国硫酸钴月度产量",
|
|
"source": "SMM",
|
|
"frequency": "月",
|
|
"unit": "吨",
|
|
"description": ""
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "未找到指定路径的节点或数据源",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
},
|
|
"examples": {
|
|
"节点不存在": {
|
|
"value": {
|
|
"detail": "未找到路径 '钴|不存在的节点' 对应的节点"
|
|
}
|
|
},
|
|
"数据源不存在": {
|
|
"value": {
|
|
"detail": "未找到数据源 'XXX' 的树状数据。可用数据源: SMM, Mysteel"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "服务器内部错误",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"schemas": {
|
|
"CategoryTreeResponse": {
|
|
"type": "object",
|
|
"description": "分类树响应对象",
|
|
"required": [
|
|
"source",
|
|
"total_metrics",
|
|
"tree"
|
|
],
|
|
"properties": {
|
|
"source": {
|
|
"type": "string",
|
|
"description": "数据源名称",
|
|
"enum": [
|
|
"SMM",
|
|
"Mysteel"
|
|
],
|
|
"example": "SMM"
|
|
},
|
|
"total_metrics": {
|
|
"type": "integer",
|
|
"description": "总指标数量",
|
|
"example": 127509
|
|
},
|
|
"tree": {
|
|
"type": "array",
|
|
"description": "树的根节点列表",
|
|
"items": {
|
|
"$ref": "#/components/schemas/TreeNode"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"TreeNode": {
|
|
"type": "object",
|
|
"description": "树节点对象",
|
|
"required": [
|
|
"name",
|
|
"path",
|
|
"level"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "节点名称",
|
|
"example": "钴"
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"description": "节点完整路径,用竖线分隔",
|
|
"example": "钴|钴化合物|硫酸钴"
|
|
},
|
|
"level": {
|
|
"type": "integer",
|
|
"description": "节点层级深度(从1开始)",
|
|
"minimum": 1,
|
|
"example": 3
|
|
},
|
|
"children": {
|
|
"type": "array",
|
|
"description": "子节点列表",
|
|
"items": {
|
|
"$ref": "#/components/schemas/TreeNode"
|
|
}
|
|
},
|
|
"metrics": {
|
|
"type": "array",
|
|
"description": "该节点下的指标列表(通常只有叶子节点有)",
|
|
"items": {
|
|
"$ref": "#/components/schemas/TreeMetric"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"TreeMetric": {
|
|
"type": "object",
|
|
"description": "树节点中的指标信息",
|
|
"required": [
|
|
"metric_id",
|
|
"metric_name",
|
|
"source",
|
|
"frequency",
|
|
"unit"
|
|
],
|
|
"properties": {
|
|
"metric_id": {
|
|
"type": "string",
|
|
"description": "指标唯一ID",
|
|
"example": "12345"
|
|
},
|
|
"metric_name": {
|
|
"type": "string",
|
|
"description": "指标名称",
|
|
"example": "SMM中国硫酸钴月度产量"
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"description": "数据源",
|
|
"enum": [
|
|
"SMM",
|
|
"Mysteel"
|
|
],
|
|
"example": "SMM"
|
|
},
|
|
"frequency": {
|
|
"type": "string",
|
|
"description": "数据频率",
|
|
"enum": [
|
|
"日",
|
|
"周",
|
|
"月"
|
|
],
|
|
"example": "月"
|
|
},
|
|
"unit": {
|
|
"type": "string",
|
|
"description": "指标单位",
|
|
"example": "吨"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "指标描述",
|
|
"example": ""
|
|
}
|
|
}
|
|
},
|
|
"ErrorResponse": {
|
|
"type": "object",
|
|
"description": "错误响应对象",
|
|
"required": [
|
|
"detail"
|
|
],
|
|
"properties": {
|
|
"detail": {
|
|
"type": "string",
|
|
"description": "错误详细信息",
|
|
"example": "未找到数据源 'XXX' 的树状数据"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"SMM完整树示例": {
|
|
"summary": "SMM完整树结构示例",
|
|
"value": {
|
|
"source": "SMM",
|
|
"total_metrics": 127509,
|
|
"tree": [
|
|
{
|
|
"name": "农业食品农资",
|
|
"path": "农业食品农资",
|
|
"level": 1,
|
|
"children": [
|
|
{
|
|
"name": "饲料",
|
|
"path": "农业食品农资|饲料",
|
|
"level": 2,
|
|
"children": []
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"name": "小金属",
|
|
"path": "小金属",
|
|
"level": 1,
|
|
"children": [
|
|
{
|
|
"name": "钴",
|
|
"path": "小金属|钴",
|
|
"level": 2,
|
|
"children": [
|
|
{
|
|
"name": "钴化合物",
|
|
"path": "小金属|钴|钴化合物",
|
|
"level": 3,
|
|
"children": []
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"Mysteel完整树示例": {
|
|
"summary": "Mysteel完整树结构示例",
|
|
"value": {
|
|
"source": "Mysteel",
|
|
"total_metrics": 272450,
|
|
"tree": [
|
|
{
|
|
"name": "钢铁产业",
|
|
"path": "钢铁产业",
|
|
"level": 1,
|
|
"children": [
|
|
{
|
|
"name": "原材料",
|
|
"path": "钢铁产业|原材料",
|
|
"level": 2,
|
|
"children": []
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"节点查询示例": {
|
|
"summary": "节点查询返回示例",
|
|
"value": {
|
|
"name": "钴化合物",
|
|
"path": "小金属|钴|钴化合物",
|
|
"level": 3,
|
|
"children": [
|
|
{
|
|
"name": "硫酸钴",
|
|
"path": "小金属|钴|钴化合物|硫酸钴",
|
|
"level": 4,
|
|
"metrics": [
|
|
{
|
|
"metric_id": "12345",
|
|
"metric_name": "SMM中国硫酸钴月度产量",
|
|
"source": "SMM",
|
|
"frequency": "月",
|
|
"unit": "吨",
|
|
"description": ""
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
} |