完善养殖端小程序
This commit is contained in:
xuqiuyun
684
backend/swagger-devices.js
Normal file
684
backend/swagger-devices.js
Normal file
@@ -0,0 +1,684 @@
|
||||
/**
|
||||
* 设备管理模块 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 };
|
||||
Reference in New Issue
Block a user