init：代码初始化
This commit is contained in:
bai
336
src/config/swagger.js
Normal file
336
src/config/swagger.js
Normal file
@@ -0,0 +1,336 @@
|
||||
const swaggerJsdoc = require('swagger-jsdoc');
|
||||
|
||||
const options = {
|
||||
definition: {
|
||||
openapi: '3.0.0',
|
||||
info: {
|
||||
title: 'Steel Prices Service API',
|
||||
version: '1.0.0',
|
||||
description: `
|
||||
钢材价格查询与分析服务平台 API 文档
|
||||
|
||||
## 功能特性
|
||||
- 📊 **价格查询** - 按地区、材质、规格等多维度查询钢材价格
|
||||
- 🔍 **智能搜索** - 支持多条件组合搜索和分页
|
||||
- 📈 **统计分析** - 价格统计、趋势分析、均价计算
|
||||
- 💾 **数据导入** - 批量导入钢材价格数据
|
||||
- 🚀 **高性能** - 数据库索引优化，查询响应快速
|
||||
|
||||
## 数据源
|
||||
- 我的钢铁网（重庆、成都、广州、南宁）
|
||||
- 德钢指导价（云南地区）
|
||||
- 云南钢协（昆明、玉溪、楚雄、大理）
|
||||
|
||||
## 认证
|
||||
当前版本无需认证，后续版本将添加 API Key 认证。
|
||||
`,
|
||||
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.00
|
||||
},
|
||||
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.50
|
||||
},
|
||||
minPrice: {
|
||||
type: 'number',
|
||||
description: '最低价格',
|
||||
example: 3500.00
|
||||
},
|
||||
maxPrice: {
|
||||
type: 'number',
|
||||
description: '最高价格',
|
||||
example: 4500.00
|
||||
},
|
||||
stdDev: {
|
||||
type: 'number',
|
||||
description: '标准差',
|
||||
example: 250.30
|
||||
},
|
||||
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.50
|
||||
},
|
||||
minPrice: {
|
||||
type: 'number',
|
||||
description: '当日最低价格',
|
||||
example: 3800.00
|
||||
},
|
||||
maxPrice: {
|
||||
type: 'number',
|
||||
description: '当日最高价格',
|
||||
example: 4100.00
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
apis: ['./src/routes/*.js', './src/controllers/*.js']
|
||||
};
|
||||
|
||||
const swaggerSpec = swaggerJsdoc(options);
|
||||
|
||||
module.exports = swaggerSpec;
|
||||
Reference in New Issue
Block a user