654 lines
17 KiB
JavaScript
654 lines
17 KiB
JavaScript
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; |