498 lines
14 KiB
JavaScript
498 lines
14 KiB
JavaScript
/**
|
||
* 宁夏智慧养殖监管平台 - 完整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; |