nxxmdata/backend/config/swagger.js

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 <token>\`

### 响应格式
所有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;