steel_prices_service/src/config/swagger.js

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;