refactor(backend): 重构动物相关 API 接口
- 更新了动物数据结构和相关类型定义 - 优化了动物列表、详情、创建、更新和删除接口 - 新增了更新动物状态接口 - 移除了与认领记录相关的接口 -调整了 API 响应结构
This commit is contained in:
ylweng
@@ -21,7 +21,7 @@ const options = {
|
||||
},
|
||||
servers: [
|
||||
{
|
||||
url: 'http://localhost:3000/api/v1',
|
||||
url: 'http://localhost:3100/api/v1',
|
||||
description: '开发环境'
|
||||
},
|
||||
{
|
||||
@@ -91,235 +91,199 @@ const options = {
|
||||
}
|
||||
}
|
||||
},
|
||||
// 用户模型
|
||||
User: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: {
|
||||
type: 'integer',
|
||||
example: 1
|
||||
},
|
||||
username: {
|
||||
type: 'string',
|
||||
example: 'testuser'
|
||||
},
|
||||
nickname: {
|
||||
type: '极速版string',
|
||||
example: '测试用户'
|
||||
},
|
||||
email: {
|
||||
type: 'string',
|
||||
example: 'test@example.com'
|
||||
},
|
||||
phone: {
|
||||
type: 'string',
|
||||
example: '13800138000'
|
||||
},
|
||||
avatar: {
|
||||
type: 'string',
|
||||
example: 'https://example.com/avatar.jpg'
|
||||
},
|
||||
gender: {
|
||||
type: 'string',
|
||||
enum: ['male', 'female', 'unknown'],
|
||||
example: 'male'
|
||||
},
|
||||
birthday: {
|
||||
type: 'string',
|
||||
format: 'date',
|
||||
example: '1990-01-01'
|
||||
},
|
||||
points: {
|
||||
type: 'integer',
|
||||
example: 1000
|
||||
},
|
||||
level: {
|
||||
type: 'integer',
|
||||
example: 3
|
||||
},
|
||||
status: {
|
||||
type: 'string',
|
||||
enum: ['active', 'inactive', 'banned'],
|
||||
example: 'active'
|
||||
},
|
||||
created_at: {
|
||||
type: 'string',
|
||||
format: 'date-time'
|
||||
},
|
||||
updated_at: {
|
||||
type: 'string',
|
||||
format: 'date-time'
|
||||
},
|
||||
last_login_at: {
|
||||
type: 'string',
|
||||
format: 'date-time',
|
||||
description: '最后登录时间'
|
||||
}
|
||||
}
|
||||
},
|
||||
// 管理员模型
|
||||
Admin: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: {
|
||||
type: 'integer',
|
||||
description: '管理员ID'
|
||||
example: 1
|
||||
},
|
||||
username: {
|
||||
type: 'string',
|
||||
description: '用户名'
|
||||
example: 'admin'
|
||||
},
|
||||
email: {
|
||||
type: 'string',
|
||||
description: '邮箱'
|
||||
example: 'admin@jiebanke.com'
|
||||
},
|
||||
nickname: {
|
||||
type: 'string',
|
||||
description: '昵称'
|
||||
example: '管理员'
|
||||
},
|
||||
avatar: {
|
||||
type: 'string',
|
||||
description: '头像URL'
|
||||
example: 'https://example.com/avatar.jpg'
|
||||
},
|
||||
role: {
|
||||
type: 'string',
|
||||
description: '角色'
|
||||
example: 'super_admin'
|
||||
},
|
||||
status: {
|
||||
type: 'integer',
|
||||
description: '状态 (1:启用, 0:禁用)'
|
||||
type: 'string',
|
||||
example: 'active'
|
||||
},
|
||||
last_login: {
|
||||
type: 'string',
|
||||
format: 'date-time',
|
||||
description: '最后登录时间'
|
||||
example: '2023-01-01T00:00:00Z'
|
||||
},
|
||||
created_at: {
|
||||
type: 'string',
|
||||
format: 'date-time',
|
||||
description: '创建时间'
|
||||
example: '2023-01-01T00:00:00Z'
|
||||
},
|
||||
updated_at: {
|
||||
type: 'string',
|
||||
format: 'date-time',
|
||||
description: '更新时间'
|
||||
example: '2023-01-01T00:00:00Z'
|
||||
}
|
||||
}
|
||||
},
|
||||
// 分页模型
|
||||
Pagination: {
|
||||
// 系统统计数据模型
|
||||
SystemStats: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
userCount: {
|
||||
type: 'integer',
|
||||
description: '用户总数'
|
||||
},
|
||||
merchantCount: {
|
||||
type: 'integer',
|
||||
description: '商家数量'
|
||||
},
|
||||
travelCount: {
|
||||
type: 'integer',
|
||||
description: '旅行计划数'
|
||||
},
|
||||
animalCount: {
|
||||
type: 'integer',
|
||||
description: '动物数量'
|
||||
},
|
||||
orderCount: {
|
||||
type: 'integer',
|
||||
description: '订单总数'
|
||||
},
|
||||
todayUserCount: {
|
||||
type: 'integer',
|
||||
description: '今日新增用户数'
|
||||
},
|
||||
todayOrderCount: {
|
||||
type: 'integer',
|
||||
description: '今日新增订单数'
|
||||
}
|
||||
}
|
||||
},
|
||||
// 用户统计数据模型
|
||||
UserStats: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
total: {
|
||||
type: 'integer',
|
||||
example: 100
|
||||
description: '用户总数'
|
||||
},
|
||||
page: {
|
||||
type: 'integer',
|
||||
example: 1
|
||||
byType: {
|
||||
type: 'array',
|
||||
description: '按类型统计',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
user_type: {
|
||||
type: 'string'
|
||||
},
|
||||
count: {
|
||||
type: 'integer'
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
pageSize: {
|
||||
byDate: {
|
||||
type: 'array',
|
||||
description: '按日期统计',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
date: {
|
||||
type: 'string'
|
||||
},
|
||||
count: {
|
||||
type: 'integer'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
// 订单统计数据模型
|
||||
OrderStats: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
total: {
|
||||
type: 'integer',
|
||||
example: 20
|
||||
description: '订单总数'
|
||||
},
|
||||
totalPages: {
|
||||
totalAmount: {
|
||||
type: 'number',
|
||||
description: '订单总金额'
|
||||
},
|
||||
byStatus: {
|
||||
type: 'array',
|
||||
description: '按状态统计',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
status: {
|
||||
type: 'string'
|
||||
},
|
||||
count: {
|
||||
type: 'integer'
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
byDate: {
|
||||
type: 'array',
|
||||
description: '按日期统计',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
date: {
|
||||
type: 'string'
|
||||
},
|
||||
count: {
|
||||
type: 'integer'
|
||||
},
|
||||
amount: {
|
||||
type: 'number'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
// 系统信息模型
|
||||
SystemInfo: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
nodeVersion: {
|
||||
type: 'string',
|
||||
description: 'Node.js版本'
|
||||
},
|
||||
platform: {
|
||||
type: 'string',
|
||||
description: '运行平台'
|
||||
},
|
||||
arch: {
|
||||
type: 'string',
|
||||
description: '系统架构'
|
||||
},
|
||||
uptime: {
|
||||
type: 'integer',
|
||||
example: 5
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
parameters: {
|
||||
// 通用分页参数
|
||||
PageParam: {
|
||||
in: 'query',
|
||||
name: 'page',
|
||||
schema: {
|
||||
type: 'integer',
|
||||
minimum: 1,
|
||||
default: 1
|
||||
},
|
||||
description: '页码'
|
||||
},
|
||||
PageSizeParam: {
|
||||
in: 'query',
|
||||
name: 'pageSize',
|
||||
schema: {
|
||||
type: 'integer',
|
||||
minimum: 1,
|
||||
maximum: 100,
|
||||
default: 20
|
||||
},
|
||||
description: '每页数量'
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
// 通用响应
|
||||
UnauthorizedError: {
|
||||
description: '未授权访问',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
},
|
||||
example: {
|
||||
success: false,
|
||||
code: 401,
|
||||
message: '未授权访问',
|
||||
error: 'Token已过期或无效',
|
||||
timestamp: '2025-01-01T00:00:00.000Z'
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
ForbiddenError: {
|
||||
description: '禁止访问',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
},
|
||||
example: {
|
||||
success: false,
|
||||
code: 403,
|
||||
message: '禁止访问',
|
||||
error: '权限不足',
|
||||
timestamp: '2025-01-01T00:00:00.000Z'
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
NotFoundError: {
|
||||
description: '资源不存在',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
},
|
||||
example: {
|
||||
success: false,
|
||||
code: 404,
|
||||
message: '资源不存在',
|
||||
error: '请求的资源不存在',
|
||||
timestamp: '2025-01-01T00:00:00.000Z'
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
ValidationError: {
|
||||
description: '参数验证错误',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
},
|
||||
example: {
|
||||
success: false,
|
||||
code: 400,
|
||||
message: '参数验证错误',
|
||||
error: '用户名必须为4-20个字符',
|
||||
timestamp: '2025-01-01T00:00:00.000Z'
|
||||
}
|
||||
description: '运行时间(秒)'
|
||||
},
|
||||
databaseVersion: {
|
||||
type: 'string',
|
||||
description: '数据库版本'
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -333,20 +297,8 @@ const options = {
|
||||
},
|
||||
apis: [
|
||||
'./src/routes/*.js',
|
||||
'./src/controllers/*.js',
|
||||
'./src/models/*.js'
|
||||
'./src/docs/*.js'
|
||||
]
|
||||
};
|
||||
|
||||
const specs = swaggerJsdoc(options);
|
||||
|
||||
module.exports = {
|
||||
swaggerUi,
|
||||
specs,
|
||||
serve: swaggerUi.serve,
|
||||
setup: swaggerUi.setup(specs, {
|
||||
explorer: true,
|
||||
customCss: '.swagger-ui .topbar { display: none }',
|
||||
customSiteTitle: '结伴客系统 API文档'
|
||||
})
|
||||
};
|
||||
module.exports = swaggerJsdoc(options);
|
||||
Reference in New Issue
Block a user