const swaggerJsdoc = require('swagger-jsdoc'); const options = { definition: { openapi: '3.0.0', info: { title: '宁夏智慧养殖监管平台 API', version: '2.1.0', description: ` ## 宁夏智慧养殖监管平台 API 文档 ### 概述 本文档提供了智慧养殖监管平台的完整API接口说明，包括： - **核心功能**: 农场管理、动物管理、设备监控、预警管理 - **业务功能**: 产品管理、订单管理、报表生成 - **系统功能**: 用户管理、权限控制、系统配置 ### 认证机制 - 采用JWT (JSON Web Token) 进行身份认证 - 所有API请求需在Header中携带Authorization字段 - 格式: \`Authorization: Bearer \` ### 响应格式 所有API响应均采用统一格式： \`\`\`json { "success": true, "data": {}, "message": "操作成功", "timestamp": "2025-01-18T10:30:00Z" } \`\`\` ### 错误处理 - HTTP状态码遵循RESTful标准 - 详细错误信息在响应体中提供 - 支持多语言错误消息 ### 版本信息 - **当前版本**: v2.1.0 - **最后更新**: 2025-01-18 - **维护状态**: 积极维护中 `, contact: { name: '技术支持', email: 'support@nxxm.com', url: 'https://github.com/nxxm-platform' }, license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' } }, servers: [ { url: 'http://localhost:5350', description: '开发服务器', }, ], components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT', } }, schemas: { MapGeocode: { type: 'object', properties: { address: { type: 'string', description: '地址' }, result: { type: 'object', properties: { location: { type: 'object', properties: { lng: { type: 'number', description: '经度' }, lat: { type: 'number', description: '纬度' } } } } } } }, MapReverseGeocode: { type: 'object', properties: { lat: { type: 'number', description: '纬度' }, lng: { type: 'number', description: '经度' }, result: { type: 'object', properties: { formatted_address: { type: 'string', description: '结构化地址' }, addressComponent: { type: 'object', description: '地址组成部分' } } } } }, MapDirection: { type: 'object', properties: { origin: { type: 'string', description: '起点坐标，格式：纬度,经度' }, destination: { type: 'string', description: '终点坐标，格式：纬度,经度' }, mode: { type: 'string', enum: ['driving', 'walking', 'riding', 'transit'], description: '交通方式' } } }, Farm: { type: 'object', properties: { id: { type: 'integer', description: '养殖场ID' }, name: { type: 'string', description: '养殖场名称' }, type: { type: 'string', description: '养殖场类型' }, location: { type: 'object', properties: { latitude: { type: 'number', format: 'float', description: '纬度' }, longitude: { type: 'number', format: 'float', description: '经度' } }, description: '地理位置' }, address: { type: 'string', description: '详细地址' }, contact: { type: 'string', description: '联系人' }, phone: { type: 'string', description: '联系电话' }, status: { type: 'string', enum: ['active', 'inactive', 'maintenance'], description: '养殖场状态' }, createdAt: { type: 'string', format: 'date-time', description: '创建时间' }, updatedAt: { type: 'string', format: 'date-time', description: '更新时间' } } }, Animal: { type: 'object', properties: { id: { type: 'integer', description: '动物ID' }, type: { type: 'string', description: '动物类型' }, count: { type: 'integer', description: '数量' }, farmId: { type: 'integer', description: '所属养殖场ID' }, health_status: { type: 'string', enum: ['healthy', 'sick', 'quarantined'], description: '健康状态' }, last_check_time: { type: 'string', format: 'date-time', description: '上次检查时间' }, notes: { type: 'string', description: '备注' }, createdAt: { type: 'string', format: 'date-time', description: '创建时间' }, updatedAt: { type: 'string', format: 'date-time', description: '更新时间' } } }, Device: { type: 'object', properties: { id: { type: 'integer', description: '设备ID' }, name: { type: 'string', description: '设备名称' }, type: { type: 'string', description: '设备类型' }, status: { type: 'string', enum: ['online', 'offline', 'maintenance'], description: '设备状态' }, farmId: { type: 'integer', description: '所属养殖场ID' }, last_maintenance: { type: 'string', format: 'date-time', description: '上次维护时间' }, installation_date: { type: 'string', format: 'date-time', description: '安装日期' }, metrics: { type: 'object', description: '设备指标' }, createdAt: { type: 'string', format: 'date-time', description: '创建时间' }, updatedAt: { type: 'string', format: 'date-time', description: '更新时间' } } }, Alert: { type: 'object', properties: { id: { type: 'integer', description: '预警ID' }, type: { type: 'string', description: '预警类型' }, level: { type: 'string', enum: ['low', 'medium', 'high', 'critical'], description: '预警级别' }, message: { type: 'string', description: '预警消息' }, status: { type: 'string', enum: ['active', 'acknowledged', 'resolved'], description: '预警状态' }, farmId: { type: 'integer', description: '所属养殖场ID' }, deviceId: { type: 'integer', description: '关联设备ID' }, resolved_at: { type: 'string', format: 'date-time', description: '解决时间' }, resolved_by: { type: 'integer', description: '解决人ID' }, resolution_notes: { type: 'string', description: '解决备注' }, createdAt: { type: 'string', format: 'date-time', description: '创建时间' }, updatedAt: { type: 'string', format: 'date-time', description: '更新时间' } } }, FarmInput: { type: 'object', required: ['name', 'type', 'location'], properties: { name: { type: 'string', description: '养殖场名称' }, type: { type: 'string', description: '养殖场类型' }, location: { type: 'object', required: ['latitude', 'longitude'], properties: { latitude: { type: 'number', format: 'float', description: '纬度' }, longitude: { type: 'number', format: 'float', description: '经度' } }, description: '地理位置' }, address: { type: 'string', description: '详细地址' }, contact: { type: 'string', description: '联系人' }, phone: { type: 'string', description: '联系电话' }, status: { type: 'string', enum: ['active', 'inactive', 'maintenance'], description: '养殖场状态', default: 'active' } } }, User: { type: 'object', properties: { id: { type: 'integer', description: '用户ID' }, username: { type: 'string', description: '用户名' }, email: { type: 'string', format: 'email', description: '邮箱地址' }, roles: { type: 'integer', description: '角色ID' }, status: { type: 'string', enum: ['active', 'inactive'], description: '用户状态' }, last_login: { type: 'string', format: 'date-time', description: '最后登录时间' } } }, Product: { type: 'object', properties: { id: { type: 'integer', description: '产品ID' }, name: { type: 'string', description: '产品名称' }, description: { type: 'string', description: '产品描述' }, price: { type: 'number', format: 'decimal', description: '产品价格' }, stock: { type: 'integer', description: '库存数量' }, status: { type: 'string', enum: ['active', 'inactive'], description: '产品状态' } } }, Order: { type: 'object', properties: { id: { type: 'integer', description: '订单ID' }, user_id: { type: 'integer', description: '用户ID' }, total_amount: { type: 'number', format: 'decimal', description: '订单总金额' }, status: { type: 'string', enum: ['pending', 'processing', 'shipped', 'delivered', 'cancelled'], description: '订单状态' }, payment_status: { type: 'string', enum: ['unpaid', 'paid', 'refunded'], description: '支付状态' }, shipping_address: { type: 'string', description: '收货地址' } } }, SystemConfig: { type: 'object', properties: { id: { type: 'integer', description: '配置ID' }, config_key: { type: 'string', description: '配置键名' }, config_value: { type: 'string', description: '配置值' }, config_type: { type: 'string', enum: ['string', 'number', 'boolean', 'json', 'array'], description: '配置类型' }, category: { type: 'string', description: '配置分类' }, description: { type: 'string', description: '配置描述' }, is_public: { type: 'boolean', description: '是否公开' }, is_editable: { type: 'boolean', description: '是否可编辑' } } }, MenuPermission: { type: 'object', properties: { id: { type: 'integer', description: '菜单ID' }, menu_key: { type: 'string', description: '菜单标识' }, menu_name: { type: 'string', description: '菜单名称' }, menu_path: { type: 'string', description: '菜单路径' }, parent_id: { type: 'integer', description: '父菜单ID' }, menu_type: { type: 'string', enum: ['page', 'button', 'api'], description: '菜单类型' }, required_roles: { type: 'array', items: { type: 'string' }, description: '所需角色' }, icon: { type: 'string', description: '菜单图标' }, sort_order: { type: 'integer', description: '排序顺序' }, is_visible: { type: 'boolean', description: '是否可见' }, is_enabled: { type: 'boolean', description: '是否启用' } } }, ApiResponse: { type: 'object', properties: { success: { type: 'boolean', description: '操作是否成功' }, data: { description: '响应数据' }, message: { type: 'string', description: '响应消息' }, timestamp: { type: 'string', format: 'date-time', description: '响应时间' } } }, ErrorResponse: { type: 'object', properties: { success: { type: 'boolean', example: false }, message: { type: 'string', description: '错误消息' }, error: { type: 'string', description: '错误详情' }, errors: { type: 'array', items: { type: 'object', properties: { field: { type: 'string', description: '错误字段' }, message: { type: 'string', description: '错误消息' } } }, description: '详细错误列表' } } } } }, security: [{ bearerAuth: [] }] }, apis: ['./routes/*.js'], // 指定包含 API 注释的文件路径 }; const specs = swaggerJsdoc(options); module.exports = specs;