完善养殖端小程序
This commit is contained in:
xuqiuyun
412
backend/swagger-auth.js
Normal file
412
backend/swagger-auth.js
Normal file
@@ -0,0 +1,412 @@
|
||||
/**
|
||||
* 用户认证模块 Swagger 文档
|
||||
* @file swagger-auth.js
|
||||
*/
|
||||
|
||||
const authPaths = {
|
||||
// 用户登录
|
||||
'/auth/login': {
|
||||
post: {
|
||||
tags: ['用户认证'],
|
||||
summary: '用户登录',
|
||||
description: '用户通过用户名/邮箱和密码登录系统',
|
||||
security: [], // 登录接口不需要认证
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
required: ['username', 'password'],
|
||||
properties: {
|
||||
username: {
|
||||
type: 'string',
|
||||
description: '用户名或邮箱',
|
||||
example: 'admin'
|
||||
},
|
||||
password: {
|
||||
type: 'string',
|
||||
description: '密码',
|
||||
example: '123456'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'200': {
|
||||
description: '登录成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '登录成功' },
|
||||
token: { type: 'string', description: 'JWT Token' },
|
||||
user: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
username: { type: 'string' },
|
||||
email: { type: 'string' },
|
||||
phone: { type: 'string' },
|
||||
avatar: { type: 'string' },
|
||||
status: { type: 'string' },
|
||||
roles: { type: 'array', items: { type: 'object' } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'400': {
|
||||
description: '请求参数错误',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
},
|
||||
'401': {
|
||||
description: '用户名或密码错误',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
},
|
||||
'429': {
|
||||
description: '登录尝试次数过多，请稍后再试',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 用户注册
|
||||
'/auth/register': {
|
||||
post: {
|
||||
tags: ['用户认证'],
|
||||
summary: '用户注册',
|
||||
description: '新用户注册账号',
|
||||
security: [], // 注册接口不需要认证
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
required: ['username', 'email', 'password'],
|
||||
properties: {
|
||||
username: {
|
||||
type: 'string',
|
||||
description: '用户名',
|
||||
example: 'newuser'
|
||||
},
|
||||
email: {
|
||||
type: 'string',
|
||||
format: 'email',
|
||||
description: '邮箱地址',
|
||||
example: 'newuser@example.com'
|
||||
},
|
||||
password: {
|
||||
type: 'string',
|
||||
minLength: 6,
|
||||
description: '密码（至少6位）',
|
||||
example: '123456'
|
||||
},
|
||||
phone: {
|
||||
type: 'string',
|
||||
description: '手机号码',
|
||||
example: '13800138000'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'201': {
|
||||
description: '注册成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '注册成功' },
|
||||
user: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
username: { type: 'string' },
|
||||
email: { type: 'string' },
|
||||
phone: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'400': {
|
||||
description: '请求参数错误或用户已存在',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 获取当前用户信息
|
||||
'/auth/me': {
|
||||
get: {
|
||||
tags: ['用户认证'],
|
||||
summary: '获取当前用户信息',
|
||||
description: '获取当前登录用户的详细信息',
|
||||
responses: {
|
||||
'200': {
|
||||
description: '获取成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
data: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
username: { type: 'string' },
|
||||
email: { type: 'string' },
|
||||
phone: { type: 'string' },
|
||||
avatar: { type: 'string' },
|
||||
status: { type: 'string' },
|
||||
roles: { type: 'array', items: { type: 'object' } },
|
||||
permissions: { type: 'array', items: { type: 'string' } },
|
||||
menus: { type: 'array', items: { type: 'object' } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'401': {
|
||||
description: '未授权，Token无效或已过期',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// Token验证
|
||||
'/auth/validate': {
|
||||
get: {
|
||||
tags: ['用户认证'],
|
||||
summary: 'Token验证',
|
||||
description: '验证当前Token是否有效',
|
||||
responses: {
|
||||
'200': {
|
||||
description: 'Token有效',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: 'Token有效' },
|
||||
user: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
username: { type: 'string' },
|
||||
email: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'401': {
|
||||
description: 'Token无效或已过期',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 获取所有角色
|
||||
'/auth/roles': {
|
||||
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: {
|
||||
id: { type: 'integer' },
|
||||
name: { type: 'string' },
|
||||
description: { type: 'string' },
|
||||
permissions: { type: 'array', items: { type: 'string' } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 为用户分配角色
|
||||
'/auth/users/{userId}/roles': {
|
||||
post: {
|
||||
tags: ['用户认证'],
|
||||
summary: '为用户分配角色',
|
||||
description: '为指定用户分配一个或多个角色',
|
||||
parameters: [
|
||||
{
|
||||
name: 'userId',
|
||||
in: 'path',
|
||||
required: true,
|
||||
schema: { type: 'integer' },
|
||||
description: '用户ID'
|
||||
}
|
||||
],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
required: ['roleIds'],
|
||||
properties: {
|
||||
roleIds: {
|
||||
type: 'array',
|
||||
items: { type: 'integer' },
|
||||
description: '角色ID列表'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'200': {
|
||||
description: '分配成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '角色分配成功' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'400': {
|
||||
description: '请求参数错误',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
},
|
||||
'404': {
|
||||
description: '用户不存在',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 移除用户角色
|
||||
'/auth/users/{userId}/roles/{roleId}': {
|
||||
delete: {
|
||||
tags: ['用户认证'],
|
||||
summary: '移除用户角色',
|
||||
description: '移除用户的指定角色',
|
||||
parameters: [
|
||||
{
|
||||
name: 'userId',
|
||||
in: 'path',
|
||||
required: true,
|
||||
schema: { type: 'integer' },
|
||||
description: '用户ID'
|
||||
},
|
||||
{
|
||||
name: 'roleId',
|
||||
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' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
module.exports = authPaths;
|
||||
Reference in New Issue
Block a user