nxxmdata/backend/swagger-integrated.js

/**
 * 宁夏智慧养殖监管平台 - 完整API文档整合配置
 * @file swagger-integrated.js
 * @description 整合所有模块的Swagger API文档
 */

const swaggerJSDoc = require('swagger-jsdoc');

// 导入各模块的Swagger文档
const { usersPaths, usersSchemas } = require('./swagger-users');
const { authPaths, authSchemas } = require('./swagger-auth');
const { farmsPaths, farmsSchemas } = require('./swagger-farms');
const { animalsPaths, animalsSchemas } = require('./swagger-animals');
const { devicesPaths, devicesSchemas } = require('./swagger-devices');
const { alertsPaths, alertSchemas } = require('./swagger-alerts');
const { smartAlertsPaths, smartAlertsSchemas } = require('./swagger-smart-alerts');
const { statsPaths, statsSchemas } = require('./swagger-stats');
const { reportsPaths, reportsSchemas } = require('./swagger-reports');
const { systemPaths, systemSchemas } = require('./swagger-system');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '宁夏智慧养殖监管平台 API',
      version: '2.0.0',
      description: `
        # 宁夏智慧养殖监管平台API文档
        
        ## 平台概述
        宁夏智慧养殖监管平台是一个集成了物联网、大数据、人工智能等技术的现代化养殖管理系统。
        
        ## 功能模块
        
        ### 🔐 用户认证与权限
        - **用户认证**: 登录、注册、JWT令牌管理
        - **用户管理**: 用户信息管理、角色权限分配
        - **权限控制**: 基于角色的访问控制(RBAC)
        
        ### 🏭 养殖场管理
        - **养殖场信息**: 养殖场基本信息管理
        - **圈舍管理**: 圈舍分配、容量管理
        - **养殖场统计**: 养殖场数据统计分析
        
        ### 🐄 动物管理
        - **动物档案**: 牲畜基本信息、健康档案
        - **批次管理**: 动物批次跟踪、转移记录
        - **繁殖管理**: 配种、产仔记录管理
        - **健康监控**: 疫苗接种、疾病记录
        
        ### 📱 设备管理
        - **IoT设备**: 智能耳标、项圈设备管理
        - **设备绑定**: 设备与动物绑定关系
        - **设备监控**: 设备状态、电量、信号监控
        - **维护记录**: 设备维护、故障记录
        
        ### ⚠️ 预警系统
        - **智能预警**: 健康、环境、设备预警
        - **预警处理**: 预警状态管理、处理记录
        - **预警统计**: 预警数据分析、趋势分析
        
        ### 🗺️ 地理信息
        - **电子围栏**: 围栏设置、越界预警
        - **位置追踪**: 动物位置实时监控
        - **地图服务**: 地图展示、轨迹回放
        
        ### 📊 数据统计
        - **实时统计**: 养殖场、动物、设备实时数据
        - **报表生成**: 各类统计报表、数据导出
        - **数据分析**: 趋势分析、预测分析
        
        ### ⚙️ 系统管理
        - **系统配置**: 系统参数配置
        - **菜单管理**: 系统菜单权限配置
        - **操作日志**: 系统操作记录审计
        - **数据备份**: 数据备份与恢复
        
        ## 认证方式
        
        本API使用JWT(JSON Web Token)进行身份认证。
        
        ### 获取Token
        1. 调用登录接口 \`POST /auth/login\` 获取访问令牌
        2. 在后续请求的Header中添加: \`Authorization: Bearer <token>\`
        
        ### Token格式
        \`\`\`
        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        \`\`\`
        
        ## 响应格式
        
        ### 成功响应
        \`\`\`json
        {
          "success": true,
          "message": "操作成功",
          "data": { ... },
          "total": 100,
          "pagination": {
            "page": 1,
            "limit": 10,
            "total": 100,
            "totalPages": 10
          }
        }
        \`\`\`
        
        ### 错误响应
        \`\`\`json
        {
          "success": false,
          "message": "错误描述",
          "error": "详细错误信息"
        }
        \`\`\`
        
        ## 状态码说明
        
        | 状态码 | 说明 |
        |--------|------|
        | 200 | 请求成功 |
        | 201 | 创建成功 |
        | 400 | 请求参数错误 |
        | 401 | 未授权访问 |
        | 403 | 权限不足 |
        | 404 | 资源不存在 |
        | 500 | 服务器内部错误 |
        
        ## 分页参数
        
        大部分列表接口支持分页查询：
        - \`page\`: 页码，从1开始
        - \`limit\`: 每页数量，默认10，最大100
        - \`search\`: 搜索关键词
        
        ## 联系方式
        
        - 开发团队: dev@nxxm.com
        - 技术支持: support@nxxm.com
        - 项目地址: https://github.com/nxxm/breeding-platform
      `,
      contact: {
        name: '宁夏智慧养殖平台开发团队',
        email: 'dev@nxxm.com',
        url: 'https://www.nxxm.com'
      },
      license: {
        name: 'MIT License',
        url: 'https://opensource.org/licenses/MIT'
      },
      termsOfService: 'https://www.nxxm.com/terms'
    },
    servers: [
      {
        url: 'http://localhost:5350/api',
        description: '本地开发环境'
      },
      {
        url: 'https://dev-api.nxxm.com/api',
        description: '开发测试环境'
      },
      {
        url: 'https://staging-api.nxxm.com/api',
        description: '预发布环境'
      },
      {
        url: 'https://api.nxxm.com/api',
        description: '生产环境'
      }
    ],
    tags: [
      {
        name: '用户认证',
        description: '用户登录、注册、JWT令牌管理',
        externalDocs: {
          description: '认证文档',
          url: 'https://docs.nxxm.com/auth'
        }
      },
      {
        name: '用户管理',
        description: '用户信息管理、角色权限分配'
      },
      {
        name: '养殖场管理',
        description: '养殖场信息的增删改查、统计分析'
      },
      {
        name: '动物管理',
        description: '牲畜信息管理、批次管理、健康档案'
      },
      {
        name: '圈舍管理',
        description: '圈舍信息管理、牲畜圈舍分配'
      },
      {
        name: '设备管理',
        description: 'IoT设备管理、设备绑定、状态监控'
      },
      {
        name: '智能设备',
        description: '智能耳标、智能项圈等设备管理'
      },
      {
        name: '预警管理',
        description: '系统预警、告警处理、预警统计'
      },
      {
        name: '智能预警',
        description: '智能耳标、项圈预警系统'
      },
      {
        name: '电子围栏',
        description: '电子围栏设置、围栏点管理'
      },
      {
        name: '地图服务',
        description: '地图相关功能、位置服务'
      },
      {
        name: '数据统计',
        description: '各类统计数据、实时监控'
      },
      {
        name: '报表管理',
        description: '报表生成、数据导出功能'
      },
      {
        name: '系统管理',
        description: '系统配置、菜单管理、权限配置'
      },
      {
        name: '备份管理',
        description: '数据备份、恢复功能'
      },
      {
        name: '操作日志',
        description: '系统操作日志记录和查询'
      },
      {
        name: '产品管理',
        description: '产品信息管理'
      },
      {
        name: '订单管理',
        description: '订单处理、订单查询'
      }
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
          description: 'JWT认证令牌，格式：Bearer <token>'
        },
        apiKey: {
          type: 'apiKey',
          in: 'header',
          name: 'X-API-Key',
          description: 'API密钥认证（用于第三方集成）'
        }
      },
      schemas: {
        // 通用响应模型
        ApiResponse: {
          type: 'object',
          properties: {
            success: {
              type: 'boolean',
              description: '请求是否成功',
              example: true
            },
            message: {
              type: 'string',
              description: '响应消息',
              example: '操作成功'
            },
            data: {
              description: '响应数据，具体结构根据接口而定'
            },
            total: {
              type: 'integer',
              description: '总记录数（分页时使用）',
              example: 100
            },
            pagination: {
              type: 'object',
              properties: {
                page: { type: 'integer', description: '当前页码', example: 1 },
                limit: { type: 'integer', description: '每页记录数', example: 10 },
                total: { type: 'integer', description: '总记录数', example: 100 },
                totalPages: { type: 'integer', description: '总页数', example: 10 }
              }
            }
          }
        },
        
        ErrorResponse: {
          type: 'object',
          properties: {
            success: {
              type: 'boolean',
              example: false,
              description: '请求是否成功'
            },
            message: {
              type: 'string',
              description: '错误消息',
              example: '请求失败'
            },
            error: {
              type: 'string',
              description: '详细错误信息',
              example: '参数验证失败'
            },
            code: {
              type: 'string',
              description: '错误代码',
              example: 'VALIDATION_ERROR'
            }
          }
        },
        
        PaginationQuery: {
          type: 'object',
          properties: {
            page: {
              type: 'integer',
              minimum: 1,
              default: 1,
              description: '页码，从1开始'
            },
            limit: {
              type: 'integer',
              minimum: 1,
              maximum: 100,
              default: 10,
              description: '每页记录数，最大100'
            },
            search: {
              type: 'string',
              description: '搜索关键词'
            },
            sortBy: {
              type: 'string',
              description: '排序字段'
            },
            sortOrder: {
              type: 'string',
              enum: ['asc', 'desc'],
              default: 'desc',
              description: '排序方向'
            }
          }
        },
        
        // 整合各模块的数据模型
        ...usersSchemas,
        ...authSchemas,
        ...farmsSchemas,
        ...animalsSchemas,
        ...devicesSchemas,
        ...alertSchemas,
        ...smartAlertsSchemas,
        ...statsSchemas,
        ...reportsSchemas,
        ...systemSchemas
      },
      
      parameters: {
        PageParam: {
          name: 'page',
          in: 'query',
          schema: { type: 'integer', minimum: 1, default: 1 },
          description: '页码'
        },
        LimitParam: {
          name: 'limit',
          in: 'query',
          schema: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
          description: '每页数量'
        },
        SearchParam: {
          name: 'search',
          in: 'query',
          schema: { type: 'string' },
          description: '搜索关键词'
        },
        IdParam: {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '资源ID'
        }
      },
      
      responses: {
        Success: {
          description: '操作成功',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ApiResponse' }
            }
          }
        },
        Created: {
          description: '创建成功',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ApiResponse' }
            }
          }
        },
        BadRequest: {
          description: '请求参数错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        Unauthorized: {
          description: '未授权访问',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        Forbidden: {
          description: '权限不足',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        NotFound: {
          description: '资源不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        InternalError: {
          description: '服务器内部错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    },
    
    security: [
      { bearerAuth: [] }
    ],
    
    // 整合所有模块的API路径
    paths: {
      ...authPaths,
      ...usersPaths,
      ...farmsPaths,
      ...animalsPaths,
      ...devicesPaths,
      ...alertsPaths,
      ...smartAlertsPaths,
      ...statsPaths,
      ...reportsPaths,
      ...systemPaths
    }
  },
  
  apis: [
    './routes/*.js',
    './controllers/*.js',
    './swagger-*.js'
  ]
};

const specs = swaggerJSDoc(options);

// 确保paths对象存在
if (!specs.paths) {
  specs.paths = {};
}

// 添加API版本信息
specs.info.version = '2.0.0';
specs.info['x-api-version'] = '2.0';
specs.info['x-build-date'] = new Date().toISOString();

module.exports = specs;