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;