975 lines
29 KiB
JSON
975 lines
29 KiB
JSON
{
|
||
"openapi": "3.0.0",
|
||
"info": {
|
||
"title": "Steel Prices Service API",
|
||
"version": "1.0.0",
|
||
"description": "\n 钢材价格查询与分析服务平台 API 文档\n\n ## 功能特性\n - 📊 **价格查询** - 按地区、材质、规格等多维度查询钢材价格\n - 🔍 **智能搜索** - 支持多条件组合搜索和分页\n - 📈 **统计分析** - 价格统计、趋势分析、均价计算\n - 💾 **数据导入** - 批量导入钢材价格数据\n - 🚀 **高性能** - 数据库索引优化，查询响应快速\n\n ## 数据源\n - 我的钢铁网（重庆、成都、广州、南宁）\n - 德钢指导价（云南地区）\n - 云南钢协（昆明、玉溪、楚雄、大理）\n\n ## 认证\n 当前版本无需认证，后续版本将添加 API Key 认证。\n ",
|
||
"contact": {
|
||
"name": "Steel Prices Service",
|
||
"email": "support@example.com"
|
||
},
|
||
"license": {
|
||
"name": "MIT",
|
||
"url": "https://opensource.org/licenses/MIT"
|
||
}
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "http://localhost:3000",
|
||
"description": "开发服务器"
|
||
},
|
||
{
|
||
"url": "https://api.steel-prices.com",
|
||
"description": "生产服务器"
|
||
}
|
||
],
|
||
"tags": [
|
||
{
|
||
"name": "Health",
|
||
"description": "健康检查和系统状态"
|
||
},
|
||
{
|
||
"name": "Prices",
|
||
"description": "价格查询、搜索和统计分析"
|
||
},
|
||
{
|
||
"name": "Data",
|
||
"description": "数据导入和管理"
|
||
}
|
||
],
|
||
"components": {
|
||
"schemas": {
|
||
"Price": {
|
||
"type": "object",
|
||
"description": "钢材价格数据模型",
|
||
"properties": {
|
||
"id": {
|
||
"type": "integer",
|
||
"description": "价格记录ID",
|
||
"example": 1
|
||
},
|
||
"region": {
|
||
"type": "string",
|
||
"description": "地区",
|
||
"example": "昆明"
|
||
},
|
||
"city": {
|
||
"type": "string",
|
||
"description": "城市",
|
||
"example": "昆明",
|
||
"nullable": true
|
||
},
|
||
"material": {
|
||
"type": "string",
|
||
"description": "材质",
|
||
"example": "HPB300"
|
||
},
|
||
"specification": {
|
||
"type": "string",
|
||
"description": "规格型号",
|
||
"example": "Φ8",
|
||
"nullable": true
|
||
},
|
||
"price": {
|
||
"type": "number",
|
||
"format": "decimal",
|
||
"description": "价格（元/吨）",
|
||
"example": 3840
|
||
},
|
||
"unit": {
|
||
"type": "string",
|
||
"description": "单位",
|
||
"example": "元/吨"
|
||
},
|
||
"date": {
|
||
"type": "string",
|
||
"format": "date",
|
||
"description": "价格日期",
|
||
"example": "2026-01-05"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"description": "数据来源",
|
||
"example": "云南钢协",
|
||
"nullable": true
|
||
},
|
||
"warehouse": {
|
||
"type": "string",
|
||
"description": "仓库/厂家",
|
||
"example": "玉昆",
|
||
"nullable": true
|
||
},
|
||
"created_at": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "创建时间"
|
||
},
|
||
"updated_at": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "更新时间"
|
||
}
|
||
},
|
||
"required": [
|
||
"region",
|
||
"material",
|
||
"price",
|
||
"date"
|
||
]
|
||
},
|
||
"SuccessResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"success": {
|
||
"type": "boolean",
|
||
"example": true
|
||
},
|
||
"data": {
|
||
"type": "object"
|
||
}
|
||
}
|
||
},
|
||
"ErrorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"success": {
|
||
"type": "boolean",
|
||
"example": false
|
||
},
|
||
"message": {
|
||
"type": "string",
|
||
"description": "错误信息",
|
||
"example": "参数验证失败"
|
||
},
|
||
"statusCode": {
|
||
"type": "integer",
|
||
"description": "HTTP 状态码",
|
||
"example": 400
|
||
}
|
||
}
|
||
},
|
||
"Pagination": {
|
||
"type": "object",
|
||
"properties": {
|
||
"page": {
|
||
"type": "integer",
|
||
"description": "当前页码",
|
||
"example": 1
|
||
},
|
||
"pageSize": {
|
||
"type": "integer",
|
||
"description": "每页数量",
|
||
"example": 20
|
||
},
|
||
"total": {
|
||
"type": "integer",
|
||
"description": "总记录数",
|
||
"example": 100
|
||
},
|
||
"totalPages": {
|
||
"type": "integer",
|
||
"description": "总页数",
|
||
"example": 5
|
||
}
|
||
}
|
||
},
|
||
"PriceStats": {
|
||
"type": "object",
|
||
"properties": {
|
||
"count": {
|
||
"type": "integer",
|
||
"description": "记录数量",
|
||
"example": 150
|
||
},
|
||
"avgPrice": {
|
||
"type": "number",
|
||
"description": "平均价格",
|
||
"example": 3950.5
|
||
},
|
||
"minPrice": {
|
||
"type": "number",
|
||
"description": "最低价格",
|
||
"example": 3500
|
||
},
|
||
"maxPrice": {
|
||
"type": "number",
|
||
"description": "最高价格",
|
||
"example": 4500
|
||
},
|
||
"stdDev": {
|
||
"type": "number",
|
||
"description": "标准差",
|
||
"example": 250.3
|
||
},
|
||
"trend": {
|
||
"type": "string",
|
||
"enum": [
|
||
"up",
|
||
"down",
|
||
"stable"
|
||
],
|
||
"description": "价格趋势",
|
||
"example": "up"
|
||
},
|
||
"changeRate": {
|
||
"type": "string",
|
||
"description": "变化率",
|
||
"example": "+2.5%"
|
||
}
|
||
}
|
||
},
|
||
"TrendData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"date": {
|
||
"type": "string",
|
||
"format": "date",
|
||
"description": "日期",
|
||
"example": "2026-01-05"
|
||
},
|
||
"avgPrice": {
|
||
"type": "number",
|
||
"description": "当日平均价格",
|
||
"example": 3950.5
|
||
},
|
||
"minPrice": {
|
||
"type": "number",
|
||
"description": "当日最低价格",
|
||
"example": 3800
|
||
},
|
||
"maxPrice": {
|
||
"type": "number",
|
||
"description": "当日最高价格",
|
||
"example": 4100
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"parameters": {
|
||
"RegionParam": {
|
||
"name": "region",
|
||
"in": "query",
|
||
"description": "地区名称（如：昆明、玉溪、大理等）",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"example": "昆明"
|
||
},
|
||
"DateParam": {
|
||
"name": "date",
|
||
"in": "query",
|
||
"description": "价格日期（格式：YYYY-MM-DD）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "date"
|
||
},
|
||
"example": "2026-01-05"
|
||
},
|
||
"MaterialParam": {
|
||
"name": "material",
|
||
"in": "query",
|
||
"description": "材质（如：HPB300、HRB400、HRB500E 等）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"example": "HPB300"
|
||
},
|
||
"DaysParam": {
|
||
"name": "days",
|
||
"in": "query",
|
||
"description": "统计天数（1-3650天）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 3650
|
||
},
|
||
"example": 30
|
||
},
|
||
"PageParam": {
|
||
"name": "page",
|
||
"in": "query",
|
||
"description": "页码（从1开始）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"default": 1
|
||
},
|
||
"example": 1
|
||
},
|
||
"PageSizeParam": {
|
||
"name": "pageSize",
|
||
"in": "query",
|
||
"description": "每页数量（1-1000）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 1000,
|
||
"default": 20
|
||
},
|
||
"example": 20
|
||
}
|
||
}
|
||
},
|
||
"paths": {
|
||
"/api/health": {
|
||
"get": {
|
||
"tags": [
|
||
"Health"
|
||
],
|
||
"summary": "健康检查",
|
||
"description": "检查服务是否正常运行",
|
||
"responses": {
|
||
"200": {
|
||
"description": "服务正常",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"success": {
|
||
"type": "boolean",
|
||
"example": true
|
||
},
|
||
"message": {
|
||
"type": "string",
|
||
"example": "Steel Prices Service is running"
|
||
},
|
||
"timestamp": {
|
||
"type": "string",
|
||
"format": "date-time"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/prices/region": {
|
||
"get": {
|
||
"tags": [
|
||
"Prices"
|
||
],
|
||
"summary": "按地区查询价格",
|
||
"description": "根据地区和日期查询钢材价格数据，支持按日期筛选或查询该地区所有价格数据",
|
||
"parameters": [
|
||
{
|
||
"$ref": "#/components/parameters/RegionParam"
|
||
},
|
||
{
|
||
"$ref": "#/components/parameters/DateParam"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "查询成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"allOf": [
|
||
{
|
||
"$ref": "#/components/schemas/SuccessResponse"
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/Price"
|
||
}
|
||
},
|
||
"total": {
|
||
"type": "integer",
|
||
"description": "返回的记录数量",
|
||
"example": 50
|
||
}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"examples": {
|
||
"query_by_region_and_date": {
|
||
"summary": "查询昆明地区 2026-01-05 的价格",
|
||
"value": {
|
||
"region": "昆明",
|
||
"date": "2026-01-05"
|
||
}
|
||
},
|
||
"query_by_region_only": {
|
||
"summary": "查询昆明地区所有价格数据",
|
||
"value": {
|
||
"region": "昆明"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/prices/search": {
|
||
"get": {
|
||
"tags": [
|
||
"Prices"
|
||
],
|
||
"summary": "搜索价格数据",
|
||
"description": "根据多个条件组合搜索钢材价格数据，支持分页返回结果。\n\n**搜索条件：**\n- material: 材质（支持模糊搜索）\n- specification: 规格型号（支持模糊搜索）\n- startDate: 开始日期\n- endDate: 结束日期\n- region: 地区\n\n**分页参数：**\n- page: 页码（默认 1）\n- pageSize: 每页数量（默认 20，最大 1000）\n",
|
||
"parameters": [
|
||
{
|
||
"name": "material",
|
||
"in": "query",
|
||
"description": "材质（支持模糊搜索，如：HPB300、HRB400、HRB500E）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"example": "HPB300"
|
||
},
|
||
{
|
||
"name": "specification",
|
||
"in": "query",
|
||
"description": "规格型号（支持模糊搜索，如：Φ8、Φ16、HRB400）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"example": "Φ8"
|
||
},
|
||
{
|
||
"name": "startDate",
|
||
"in": "query",
|
||
"description": "开始日期（格式：YYYY-MM-DD）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "date"
|
||
},
|
||
"example": "2026-01-01"
|
||
},
|
||
{
|
||
"name": "endDate",
|
||
"in": "query",
|
||
"description": "结束日期（格式：YYYY-MM-DD）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "date"
|
||
},
|
||
"example": "2026-01-05"
|
||
},
|
||
{
|
||
"name": "region",
|
||
"in": "query",
|
||
"description": "地区",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"example": "昆明"
|
||
},
|
||
{
|
||
"$ref": "#/components/parameters/PageParam"
|
||
},
|
||
{
|
||
"$ref": "#/components/parameters/PageSizeParam"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "搜索成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"allOf": [
|
||
{
|
||
"$ref": "#/components/schemas/SuccessResponse"
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/Price"
|
||
}
|
||
},
|
||
"pagination": {
|
||
"$ref": "#/components/schemas/Pagination"
|
||
}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"examples": {
|
||
"search_by_material": {
|
||
"summary": "按材质搜索",
|
||
"value": {
|
||
"material": "HPB300",
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
},
|
||
"search_by_date_range": {
|
||
"summary": "按日期范围搜索",
|
||
"value": {
|
||
"material": "HRB400",
|
||
"startDate": "2026-01-01",
|
||
"endDate": "2026-01-05",
|
||
"page": 1,
|
||
"pageSize": 50
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/prices/stats": {
|
||
"get": {
|
||
"tags": [
|
||
"Prices"
|
||
],
|
||
"summary": "获取价格统计",
|
||
"description": "获取钢材价格的统计数据，包括平均值、最大值、最小值、标准差等。\n\n**筛选条件：**\n- region: 指定地区\n- material: 指定材质\n- days: 统计最近 N 天的数据\n- startDate/endDate: 指定日期范围\n\n**统计指标：**\n- count: 记录数量\n- avgPrice: 平均价格\n- minPrice: 最低价格\n- maxPrice: 最高价格\n- stdDev: 标准差\n- trend: 价格趋势（up/down/stable）\n- changeRate: 变化率（相对于上一周期）\n",
|
||
"parameters": [
|
||
{
|
||
"name": "region",
|
||
"in": "query",
|
||
"description": "地区（可选）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"example": "昆明"
|
||
},
|
||
{
|
||
"name": "material",
|
||
"in": "query",
|
||
"description": "材质（可选，支持模糊搜索）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"example": "HPB300"
|
||
},
|
||
{
|
||
"$ref": "#/components/parameters/DaysParam"
|
||
},
|
||
{
|
||
"name": "startDate",
|
||
"in": "query",
|
||
"description": "开始日期（格式：YYYY-MM-DD）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "date"
|
||
},
|
||
"example": "2026-01-01"
|
||
},
|
||
{
|
||
"name": "endDate",
|
||
"in": "query",
|
||
"description": "结束日期（格式：YYYY-MM-DD）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "date"
|
||
},
|
||
"example": "2026-01-05"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "统计成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"allOf": [
|
||
{
|
||
"$ref": "#/components/schemas/SuccessResponse"
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"$ref": "#/components/schemas/PriceStats"
|
||
}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"examples": {
|
||
"stats_by_region_and_days": {
|
||
"summary": "统计昆明地区最近 30 天的 HPB300 价格",
|
||
"value": {
|
||
"region": "昆明",
|
||
"material": "HPB300",
|
||
"days": 30
|
||
}
|
||
},
|
||
"stats_by_date_range": {
|
||
"summary": "统计指定日期范围内的价格",
|
||
"value": {
|
||
"startDate": "2026-01-01",
|
||
"endDate": "2026-01-05"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/prices/trend": {
|
||
"get": {
|
||
"tags": [
|
||
"Prices"
|
||
],
|
||
"summary": "获取价格趋势",
|
||
"description": "获取钢材价格的时间序列趋势数据，按日期分组统计。\n\n**筛选条件：**\n- region: 指定地区\n- material: 指定材质\n- days: 统计最近 N 天的数据\n\n**返回数据：**\n- date: 日期\n- avgPrice: 当日平均价格\n- minPrice: 当日最低价格\n- maxPrice: 当日最高价格\n\n**适用场景：**\n- 绘制价格走势图\n- 分析价格波动规律\n- 预测价格趋势\n",
|
||
"parameters": [
|
||
{
|
||
"name": "region",
|
||
"in": "query",
|
||
"description": "地区（可选）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"example": "昆明"
|
||
},
|
||
{
|
||
"name": "material",
|
||
"in": "query",
|
||
"description": "材质（可选，支持模糊搜索）",
|
||
"required": false,
|
||
"schema": {
|
||
"type": "string"
|
||
},
|
||
"example": "HPB300"
|
||
},
|
||
{
|
||
"$ref": "#/components/parameters/DaysParam"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "查询成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"allOf": [
|
||
{
|
||
"$ref": "#/components/schemas/SuccessResponse"
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/TrendData"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"examples": {
|
||
"trend_by_region": {
|
||
"summary": "获取昆明地区最近 30 天的价格趋势",
|
||
"value": {
|
||
"region": "昆明",
|
||
"days": 30
|
||
}
|
||
},
|
||
"trend_by_material": {
|
||
"summary": "获取 HPB300 最近 60 天的价格趋势",
|
||
"value": {
|
||
"material": "HPB300",
|
||
"days": 60
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/prices/import": {
|
||
"post": {
|
||
"tags": [
|
||
"Data"
|
||
],
|
||
"summary": "导入价格数据",
|
||
"description": "批量导入钢材价格数据到数据库。\n\n**请求体格式：**\n```json\n{\n \"prices\": [\n {\n \"region\": \"昆明\",\n \"city\": \"昆明\",\n \"material\": \"HPB300\",\n \"specification\": \"Φ8\",\n \"price\": 3840.00,\n \"unit\": \"元/吨\",\n \"date\": \"2026-01-05\",\n \"source\": \"云南钢协\",\n \"warehouse\": \"玉昆\"\n }\n ]\n}\n```\n\n**注意事项：**\n- 必填字段：region, material, price, date\n- price 必须为数字类型\n- date 格式必须为 YYYY-MM-DD\n- 重复数据会自动更新\n",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"required": [
|
||
"prices"
|
||
],
|
||
"properties": {
|
||
"prices": {
|
||
"type": "array",
|
||
"description": "价格数据数组",
|
||
"items": {
|
||
"type": "object",
|
||
"required": [
|
||
"region",
|
||
"material",
|
||
"price",
|
||
"date"
|
||
],
|
||
"properties": {
|
||
"region": {
|
||
"type": "string",
|
||
"description": "地区",
|
||
"example": "昆明"
|
||
},
|
||
"city": {
|
||
"type": "string",
|
||
"description": "城市",
|
||
"example": "昆明"
|
||
},
|
||
"material": {
|
||
"type": "string",
|
||
"description": "材质",
|
||
"example": "HPB300"
|
||
},
|
||
"specification": {
|
||
"type": "string",
|
||
"description": "规格型号",
|
||
"example": "Φ8"
|
||
},
|
||
"price": {
|
||
"type": "number",
|
||
"format": "decimal",
|
||
"description": "价格",
|
||
"example": 3840
|
||
},
|
||
"unit": {
|
||
"type": "string",
|
||
"description": "单位",
|
||
"example": "元/吨"
|
||
},
|
||
"date": {
|
||
"type": "string",
|
||
"format": "date",
|
||
"description": "日期",
|
||
"example": "2026-01-05"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"description": "数据来源",
|
||
"example": "云南钢协"
|
||
},
|
||
"warehouse": {
|
||
"type": "string",
|
||
"description": "仓库/厂家",
|
||
"example": "玉昆"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"examples": {
|
||
"single_record": {
|
||
"summary": "单条记录",
|
||
"value": {
|
||
"prices": [
|
||
{
|
||
"region": "昆明",
|
||
"city": "昆明",
|
||
"material": "HPB300",
|
||
"specification": "Φ8",
|
||
"price": 3840,
|
||
"unit": "元/吨",
|
||
"date": "2026-01-05",
|
||
"source": "云南钢协",
|
||
"warehouse": "玉昆"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"multiple_records": {
|
||
"summary": "多条记录",
|
||
"value": {
|
||
"prices": [
|
||
{
|
||
"region": "昆明",
|
||
"material": "HPB300",
|
||
"price": 3840,
|
||
"date": "2026-01-05",
|
||
"source": "云南钢协"
|
||
},
|
||
{
|
||
"region": "玉溪",
|
||
"material": "HRB400",
|
||
"price": 3750,
|
||
"date": "2026-01-05",
|
||
"source": "德钢指导价"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "导入成功",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"allOf": [
|
||
{
|
||
"$ref": "#/components/schemas/SuccessResponse"
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"message": {
|
||
"type": "string",
|
||
"example": "成功导入 100 条数据"
|
||
},
|
||
"data": {
|
||
"type": "object",
|
||
"properties": {
|
||
"imported": {
|
||
"type": "integer",
|
||
"description": "实际导入的记录数",
|
||
"example": 100
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "参数错误或数据格式错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "服务器错误",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
} |