223 lines
5.5 KiB
JavaScript
223 lines
5.5 KiB
JavaScript
/**
|
||
* 完整版Swagger配置
|
||
* @file swagger-complete.js
|
||
* @description 宁夏智慧养殖监管平台完整API文档配置
|
||
*/
|
||
|
||
const swaggerJSDoc = require('swagger-jsdoc');
|
||
|
||
const options = {
|
||
definition: {
|
||
openapi: '3.0.0',
|
||
info: {
|
||
title: '宁夏智慧养殖监管平台 API',
|
||
version: '2.0.0',
|
||
description: `
|
||
宁夏智慧养殖监管平台API文档
|
||
|
||
## 功能模块
|
||
- **用户认证**: 登录、注册、权限验证
|
||
- **用户管理**: 用户CRUD操作、角色管理
|
||
- **养殖场管理**: 养殖场信息管理
|
||
- **动物管理**: 牲畜信息管理、批次管理
|
||
- **设备管理**: IoT设备管理、智能设备
|
||
- **预警系统**: 智能预警、告警处理
|
||
- **围栏管理**: 电子围栏设置
|
||
- **数据统计**: 各类统计报表
|
||
- **系统管理**: 系统配置、备份等
|
||
|
||
## 认证方式
|
||
使用JWT Token进行身份认证，请在请求头中添加：
|
||
\`Authorization: Bearer <token>\`
|
||
`,
|
||
contact: {
|
||
name: '开发团队',
|
||
email: 'dev@nxxm.com'
|
||
},
|
||
license: {
|
||
name: 'MIT',
|
||
url: 'https://opensource.org/licenses/MIT'
|
||
}
|
||
},
|
||
servers: [
|
||
{
|
||
url: 'http://localhost:5350/api',
|
||
description: '开发环境'
|
||
},
|
||
{
|
||
url: 'https://api.nxxm.com/api',
|
||
description: '生产环境'
|
||
}
|
||
],
|
||
tags: [
|
||
{
|
||
name: '用户认证',
|
||
description: '用户登录、注册、权限验证相关接口'
|
||
},
|
||
{
|
||
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: '订单处理、订单查询'
|
||
}
|
||
],
|
||
components: {
|
||
securitySchemes: {
|
||
bearerAuth: {
|
||
type: 'http',
|
||
scheme: 'bearer',
|
||
bearerFormat: 'JWT',
|
||
description: 'JWT认证，格式：Bearer <token>'
|
||
}
|
||
},
|
||
schemas: {
|
||
// 通用响应格式
|
||
ApiResponse: {
|
||
type: 'object',
|
||
properties: {
|
||
success: {
|
||
type: 'boolean',
|
||
description: '请求是否成功'
|
||
},
|
||
message: {
|
||
type: 'string',
|
||
description: '响应消息'
|
||
},
|
||
data: {
|
||
description: '响应数据'
|
||
},
|
||
total: {
|
||
type: 'integer',
|
||
description: '总记录数（分页时使用）'
|
||
},
|
||
page: {
|
||
type: 'integer',
|
||
description: '当前页码'
|
||
},
|
||
limit: {
|
||
type: 'integer',
|
||
description: '每页记录数'
|
||
}
|
||
}
|
||
},
|
||
// 错误响应
|
||
ErrorResponse: {
|
||
type: 'object',
|
||
properties: {
|
||
success: {
|
||
type: 'boolean',
|
||
example: false
|
||
},
|
||
message: {
|
||
type: 'string',
|
||
description: '错误消息'
|
||
},
|
||
error: {
|
||
type: 'string',
|
||
description: '错误详情'
|
||
}
|
||
}
|
||
},
|
||
// 分页参数
|
||
PaginationQuery: {
|
||
type: 'object',
|
||
properties: {
|
||
page: {
|
||
type: 'integer',
|
||
minimum: 1,
|
||
default: 1,
|
||
description: '页码'
|
||
},
|
||
limit: {
|
||
type: 'integer',
|
||
minimum: 1,
|
||
maximum: 100,
|
||
default: 10,
|
||
description: '每页记录数'
|
||
},
|
||
search: {
|
||
type: 'string',
|
||
description: '搜索关键词'
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
security: [
|
||
{
|
||
bearerAuth: []
|
||
}
|
||
]
|
||
},
|
||
apis: [
|
||
'./routes/*.js',
|
||
'./controllers/*.js'
|
||
]
|
||
};
|
||
|
||
const specs = swaggerJSDoc(options);
|
||
|
||
// 手动添加API路径定义
|
||
if (!specs.paths) {
|
||
specs.paths = {};
|
||
}
|
||
|
||
module.exports = specs; |