684 lines
21 KiB
JavaScript
684 lines
21 KiB
JavaScript
/**
|
||
* 设备管理模块 Swagger 文档
|
||
* @file swagger-devices.js
|
||
*/
|
||
|
||
const devicesPaths = {
|
||
// 获取所有设备
|
||
'/devices': {
|
||
get: {
|
||
tags: ['设备管理'],
|
||
summary: '获取设备列表',
|
||
description: '分页获取系统中的所有设备信息',
|
||
parameters: [
|
||
{
|
||
name: 'page',
|
||
in: 'query',
|
||
schema: { type: 'integer', default: 1 },
|
||
description: '页码'
|
||
},
|
||
{
|
||
name: 'limit',
|
||
in: 'query',
|
||
schema: { type: 'integer', default: 10 },
|
||
description: '每页数量'
|
||
},
|
||
{
|
||
name: 'search',
|
||
in: 'query',
|
||
schema: { type: 'string' },
|
||
description: '搜索关键词（设备名称、设备编号）'
|
||
},
|
||
{
|
||
name: 'type',
|
||
in: 'query',
|
||
schema: { type: 'string' },
|
||
description: '设备类型筛选'
|
||
},
|
||
{
|
||
name: 'status',
|
||
in: 'query',
|
||
schema: { type: 'string', enum: ['online', 'offline', 'maintenance', 'error'] },
|
||
description: '设备状态筛选'
|
||
},
|
||
{
|
||
name: 'farmId',
|
||
in: 'query',
|
||
schema: { type: 'integer' },
|
||
description: '养殖场ID筛选'
|
||
}
|
||
],
|
||
responses: {
|
||
'200': {
|
||
description: '获取成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
data: {
|
||
type: 'array',
|
||
items: { $ref: '#/components/schemas/Device' }
|
||
},
|
||
pagination: {
|
||
type: 'object',
|
||
properties: {
|
||
page: { type: 'integer' },
|
||
limit: { type: 'integer' },
|
||
total: { type: 'integer' },
|
||
totalPages: { type: 'integer' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
post: {
|
||
tags: ['设备管理'],
|
||
summary: '创建新设备',
|
||
description: '添加新的设备到系统中',
|
||
requestBody: {
|
||
required: true,
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
required: ['name', 'type', 'farmId'],
|
||
properties: {
|
||
name: { type: 'string', description: '设备名称' },
|
||
type: {
|
||
type: 'string',
|
||
enum: ['collar', 'ear_tag', 'temperature_sensor', 'humidity_sensor', 'camera', 'feeder', 'water_dispenser'],
|
||
description: '设备类型'
|
||
},
|
||
deviceNumber: { type: 'string', description: '设备编号' },
|
||
model: { type: 'string', description: '设备型号' },
|
||
manufacturer: { type: 'string', description: '制造商' },
|
||
status: {
|
||
type: 'string',
|
||
enum: ['online', 'offline', 'maintenance', 'error'],
|
||
default: 'offline',
|
||
description: '设备状态'
|
||
},
|
||
farmId: { type: 'integer', description: '所属养殖场ID' },
|
||
location: { type: 'string', description: '设备位置' },
|
||
installationDate: { type: 'string', format: 'date', description: '安装日期' },
|
||
lastMaintenance: { type: 'string', format: 'date', description: '最近维护时间' },
|
||
batteryLevel: { type: 'number', minimum: 0, maximum: 100, description: '电池电量（%）' },
|
||
firmwareVersion: { type: 'string', description: '固件版本' },
|
||
specifications: { type: 'object', description: '设备规格参数' },
|
||
notes: { type: 'string', description: '备注' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
responses: {
|
||
'201': {
|
||
description: '创建成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
message: { type: 'string', example: '设备创建成功' },
|
||
data: { $ref: '#/components/schemas/Device' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
'400': {
|
||
description: '请求参数错误',
|
||
content: {
|
||
'application/json': {
|
||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
|
||
// 公共设备数据
|
||
'/devices/public': {
|
||
get: {
|
||
tags: ['设备管理'],
|
||
summary: '获取公共设备数据',
|
||
description: '获取可公开访问的设备基本信息',
|
||
security: [], // 公共接口不需要认证
|
||
parameters: [
|
||
{
|
||
name: 'type',
|
||
in: 'query',
|
||
schema: { type: 'string' },
|
||
description: '设备类型筛选'
|
||
},
|
||
{
|
||
name: 'status',
|
||
in: 'query',
|
||
schema: { type: 'string' },
|
||
description: '设备状态筛选'
|
||
}
|
||
],
|
||
responses: {
|
||
'200': {
|
||
description: '获取成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
data: {
|
||
type: 'array',
|
||
items: {
|
||
type: 'object',
|
||
properties: {
|
||
id: { type: 'integer' },
|
||
name: { type: 'string' },
|
||
type: { type: 'string' },
|
||
status: { type: 'string' },
|
||
location: { type: 'string' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
|
||
// 搜索设备
|
||
'/devices/search': {
|
||
get: {
|
||
tags: ['设备管理'],
|
||
summary: '搜索设备',
|
||
description: '根据设备名称搜索设备',
|
||
parameters: [
|
||
{
|
||
name: 'name',
|
||
in: 'query',
|
||
required: true,
|
||
schema: { type: 'string' },
|
||
description: '设备名称关键词'
|
||
},
|
||
{
|
||
name: 'limit',
|
||
in: 'query',
|
||
schema: { type: 'integer', default: 10 },
|
||
description: '返回结果数量限制'
|
||
}
|
||
],
|
||
responses: {
|
||
'200': {
|
||
description: '搜索成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
data: {
|
||
type: 'array',
|
||
items: { $ref: '#/components/schemas/Device' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
|
||
// 设备统计 - 按状态
|
||
'/devices/stats/status': {
|
||
get: {
|
||
tags: ['设备管理'],
|
||
summary: '按状态统计设备数量',
|
||
description: '获取不同状态下的设备数量统计',
|
||
responses: {
|
||
'200': {
|
||
description: '统计成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
data: {
|
||
type: 'array',
|
||
items: {
|
||
type: 'object',
|
||
properties: {
|
||
status: { type: 'string', example: 'online' },
|
||
count: { type: 'integer', example: 25 },
|
||
percentage: { type: 'number', example: 62.5 }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
|
||
// 设备统计 - 按类型
|
||
'/devices/stats/type': {
|
||
get: {
|
||
tags: ['设备管理'],
|
||
summary: '按类型统计设备数量',
|
||
description: '获取不同类型设备的数量统计',
|
||
responses: {
|
||
'200': {
|
||
description: '统计成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
data: {
|
||
type: 'array',
|
||
items: {
|
||
type: 'object',
|
||
properties: {
|
||
type: { type: 'string', example: 'collar' },
|
||
typeName: { type: 'string', example: '智能项圈' },
|
||
count: { type: 'integer', example: 15 },
|
||
percentage: { type: 'number', example: 37.5 }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
|
||
// 获取指定设备详情
|
||
'/devices/{id}': {
|
||
get: {
|
||
tags: ['设备管理'],
|
||
summary: '获取设备详情',
|
||
description: '根据设备ID获取详细信息',
|
||
parameters: [
|
||
{
|
||
name: 'id',
|
||
in: 'path',
|
||
required: true,
|
||
schema: { type: 'integer' },
|
||
description: '设备ID'
|
||
}
|
||
],
|
||
responses: {
|
||
'200': {
|
||
description: '获取成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
data: { $ref: '#/components/schemas/Device' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
'404': {
|
||
description: '设备不存在',
|
||
content: {
|
||
'application/json': {
|
||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
put: {
|
||
tags: ['设备管理'],
|
||
summary: '更新设备信息',
|
||
description: '更新指定设备的信息',
|
||
parameters: [
|
||
{
|
||
name: 'id',
|
||
in: 'path',
|
||
required: true,
|
||
schema: { type: 'integer' },
|
||
description: '设备ID'
|
||
}
|
||
],
|
||
requestBody: {
|
||
required: true,
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
name: { type: 'string', description: '设备名称' },
|
||
type: { type: 'string', description: '设备类型' },
|
||
deviceNumber: { type: 'string', description: '设备编号' },
|
||
model: { type: 'string', description: '设备型号' },
|
||
manufacturer: { type: 'string', description: '制造商' },
|
||
status: {
|
||
type: 'string',
|
||
enum: ['online', 'offline', 'maintenance', 'error'],
|
||
description: '设备状态'
|
||
},
|
||
farmId: { type: 'integer', description: '所属养殖场ID' },
|
||
location: { type: 'string', description: '设备位置' },
|
||
lastMaintenance: { type: 'string', format: 'date', description: '最近维护时间' },
|
||
batteryLevel: { type: 'number', minimum: 0, maximum: 100, description: '电池电量（%）' },
|
||
firmwareVersion: { type: 'string', description: '固件版本' },
|
||
specifications: { type: 'object', description: '设备规格参数' },
|
||
notes: { type: 'string', description: '备注' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
responses: {
|
||
'200': {
|
||
description: '更新成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
message: { type: 'string', example: '设备信息更新成功' },
|
||
data: { $ref: '#/components/schemas/Device' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
'400': {
|
||
description: '请求参数错误',
|
||
content: {
|
||
'application/json': {
|
||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||
}
|
||
}
|
||
},
|
||
'404': {
|
||
description: '设备不存在',
|
||
content: {
|
||
'application/json': {
|
||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
delete: {
|
||
tags: ['设备管理'],
|
||
summary: '删除设备',
|
||
description: '删除指定设备（软删除）',
|
||
parameters: [
|
||
{
|
||
name: 'id',
|
||
in: 'path',
|
||
required: true,
|
||
schema: { type: 'integer' },
|
||
description: '设备ID'
|
||
}
|
||
],
|
||
responses: {
|
||
'200': {
|
||
description: '删除成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
message: { type: 'string', example: '设备删除成功' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
'404': {
|
||
description: '设备不存在',
|
||
content: {
|
||
'application/json': {
|
||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
|
||
// 设备维护记录
|
||
'/devices/{id}/maintenance': {
|
||
get: {
|
||
tags: ['设备管理'],
|
||
summary: '获取设备维护记录',
|
||
description: '获取指定设备的维护记录',
|
||
parameters: [
|
||
{
|
||
name: 'id',
|
||
in: 'path',
|
||
required: true,
|
||
schema: { type: 'integer' },
|
||
description: '设备ID'
|
||
}
|
||
],
|
||
responses: {
|
||
'200': {
|
||
description: '获取成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
data: {
|
||
type: 'array',
|
||
items: {
|
||
type: 'object',
|
||
properties: {
|
||
id: { type: 'integer' },
|
||
deviceId: { type: 'integer' },
|
||
maintenanceDate: { type: 'string', format: 'date' },
|
||
maintenanceType: { type: 'string', enum: ['routine', 'repair', 'upgrade'] },
|
||
description: { type: 'string' },
|
||
technician: { type: 'string' },
|
||
cost: { type: 'number' },
|
||
notes: { type: 'string' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
post: {
|
||
tags: ['设备管理'],
|
||
summary: '添加设备维护记录',
|
||
description: '为指定设备添加维护记录',
|
||
parameters: [
|
||
{
|
||
name: 'id',
|
||
in: 'path',
|
||
required: true,
|
||
schema: { type: 'integer' },
|
||
description: '设备ID'
|
||
}
|
||
],
|
||
requestBody: {
|
||
required: true,
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
required: ['maintenanceDate', 'maintenanceType', 'description'],
|
||
properties: {
|
||
maintenanceDate: { type: 'string', format: 'date', description: '维护日期' },
|
||
maintenanceType: {
|
||
type: 'string',
|
||
enum: ['routine', 'repair', 'upgrade'],
|
||
description: '维护类型'
|
||
},
|
||
description: { type: 'string', description: '维护描述' },
|
||
technician: { type: 'string', description: '技术员姓名' },
|
||
cost: { type: 'number', description: '维护费用' },
|
||
notes: { type: 'string', description: '备注' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
responses: {
|
||
'201': {
|
||
description: '添加成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
message: { type: 'string', example: '维护记录添加成功' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
|
||
// 设备数据监控
|
||
'/devices/{id}/data': {
|
||
get: {
|
||
tags: ['设备管理'],
|
||
summary: '获取设备监控数据',
|
||
description: '获取指定设备的实时监控数据',
|
||
parameters: [
|
||
{
|
||
name: 'id',
|
||
in: 'path',
|
||
required: true,
|
||
schema: { type: 'integer' },
|
||
description: '设备ID'
|
||
},
|
||
{
|
||
name: 'startTime',
|
||
in: 'query',
|
||
schema: { type: 'string', format: 'date-time' },
|
||
description: '开始时间'
|
||
},
|
||
{
|
||
name: 'endTime',
|
||
in: 'query',
|
||
schema: { type: 'string', format: 'date-time' },
|
||
description: '结束时间'
|
||
},
|
||
{
|
||
name: 'dataType',
|
||
in: 'query',
|
||
schema: { type: 'string', enum: ['temperature', 'humidity', 'location', 'battery', 'activity'] },
|
||
description: '数据类型'
|
||
}
|
||
],
|
||
responses: {
|
||
'200': {
|
||
description: '获取成功',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: { type: 'boolean', example: true },
|
||
data: {
|
||
type: 'array',
|
||
items: {
|
||
type: 'object',
|
||
properties: {
|
||
timestamp: { type: 'string', format: 'date-time' },
|
||
dataType: { type: 'string' },
|
||
value: { type: 'number' },
|
||
unit: { type: 'string' },
|
||
location: {
|
||
type: 'object',
|
||
properties: {
|
||
latitude: { type: 'number' },
|
||
longitude: { type: 'number' }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
};
|
||
|
||
// 设备数据模型
|
||
const deviceSchemas = {
|
||
Device: {
|
||
type: 'object',
|
||
properties: {
|
||
id: { type: 'integer', description: '设备ID' },
|
||
name: { type: 'string', description: '设备名称' },
|
||
type: {
|
||
type: 'string',
|
||
enum: ['collar', 'ear_tag', 'temperature_sensor', 'humidity_sensor', 'camera', 'feeder', 'water_dispenser'],
|
||
description: '设备类型'
|
||
},
|
||
deviceNumber: { type: 'string', description: '设备编号' },
|
||
model: { type: 'string', description: '设备型号' },
|
||
manufacturer: { type: 'string', description: '制造商' },
|
||
status: {
|
||
type: 'string',
|
||
enum: ['online', 'offline', 'maintenance', 'error'],
|
||
description: '设备状态'
|
||
},
|
||
farmId: { type: 'integer', description: '所属养殖场ID' },
|
||
farmName: { type: 'string', description: '养殖场名称' },
|
||
location: { type: 'string', description: '设备位置' },
|
||
installationDate: { type: 'string', format: 'date', description: '安装日期' },
|
||
lastMaintenance: { type: 'string', format: 'date', description: '最近维护时间' },
|
||
batteryLevel: { type: 'number', minimum: 0, maximum: 100, description: '电池电量（%）' },
|
||
firmwareVersion: { type: 'string', description: '固件版本' },
|
||
specifications: {
|
||
type: 'object',
|
||
description: '设备规格参数',
|
||
additionalProperties: true
|
||
},
|
||
lastDataTime: { type: 'string', format: 'date-time', description: '最后数据时间' },
|
||
isActive: { type: 'boolean', description: '是否激活' },
|
||
notes: { type: 'string', description: '备注' },
|
||
createdAt: { type: 'string', format: 'date-time', description: '创建时间' },
|
||
updatedAt: { type: 'string', format: 'date-time', description: '更新时间' }
|
||
}
|
||
}
|
||
};
|
||
|
||
module.exports = { devicesPaths, deviceSchemas }; |