139 lines
4.0 KiB
JavaScript
139 lines
4.0 KiB
JavaScript
/**
|
|
* 用户管理模块 Swagger 文档
|
|
* @file swagger-users.js
|
|
* @description 用户管理相关的 Swagger API 文档定义
|
|
*/
|
|
|
|
// 用户管理相关的 API 路径定义
|
|
const usersPaths = {
|
|
'/api/users': {
|
|
get: {
|
|
summary: '获取所有用户',
|
|
tags: ['用户管理'],
|
|
security: [{ bearerAuth: [] }],
|
|
parameters: [
|
|
{ $ref: '#/components/parameters/PageParam' },
|
|
{ $ref: '#/components/parameters/LimitParam' },
|
|
{ $ref: '#/components/parameters/SearchParam' }
|
|
],
|
|
responses: {
|
|
200: { $ref: '#/components/responses/Success' },
|
|
401: { $ref: '#/components/responses/Unauthorized' }
|
|
}
|
|
},
|
|
post: {
|
|
summary: '创建新用户',
|
|
tags: ['用户管理'],
|
|
security: [{ bearerAuth: [] }],
|
|
requestBody: {
|
|
required: true,
|
|
content: {
|
|
'application/json': {
|
|
schema: { $ref: '#/components/schemas/UserInput' }
|
|
}
|
|
}
|
|
},
|
|
responses: {
|
|
201: { $ref: '#/components/responses/Created' },
|
|
400: { $ref: '#/components/responses/BadRequest' }
|
|
}
|
|
}
|
|
},
|
|
'/api/users/{id}': {
|
|
get: {
|
|
summary: '根据ID获取用户',
|
|
tags: ['用户管理'],
|
|
security: [{ bearerAuth: [] }],
|
|
parameters: [{ $ref: '#/components/parameters/IdParam' }],
|
|
responses: {
|
|
200: { $ref: '#/components/responses/Success' },
|
|
404: { $ref: '#/components/responses/NotFound' }
|
|
}
|
|
},
|
|
put: {
|
|
summary: '更新用户信息',
|
|
tags: ['用户管理'],
|
|
security: [{ bearerAuth: [] }],
|
|
parameters: [{ $ref: '#/components/parameters/IdParam' }],
|
|
requestBody: {
|
|
required: true,
|
|
content: {
|
|
'application/json': {
|
|
schema: { $ref: '#/components/schemas/UserInput' }
|
|
}
|
|
}
|
|
},
|
|
responses: {
|
|
200: { $ref: '#/components/responses/Success' },
|
|
404: { $ref: '#/components/responses/NotFound' }
|
|
}
|
|
},
|
|
delete: {
|
|
summary: '删除用户',
|
|
tags: ['用户管理'],
|
|
security: [{ bearerAuth: [] }],
|
|
parameters: [{ $ref: '#/components/parameters/IdParam' }],
|
|
responses: {
|
|
200: { $ref: '#/components/responses/Success' },
|
|
404: { $ref: '#/components/responses/NotFound' }
|
|
}
|
|
}
|
|
},
|
|
'/api/users/search': {
|
|
get: {
|
|
summary: '搜索用户',
|
|
tags: ['用户管理'],
|
|
security: [{ bearerAuth: [] }],
|
|
parameters: [
|
|
{ $ref: '#/components/parameters/SearchParam' }
|
|
],
|
|
responses: {
|
|
200: { $ref: '#/components/responses/Success' }
|
|
}
|
|
}
|
|
}
|
|
};
|
|
|
|
// 用户管理相关的数据模型定义
|
|
const usersSchemas = {
|
|
User: {
|
|
type: 'object',
|
|
properties: {
|
|
id: { type: 'integer', description: '用户ID' },
|
|
username: { type: 'string', description: '用户名' },
|
|
email: { type: 'string', format: 'email', description: '邮箱地址' },
|
|
phone: { type: 'string', description: '手机号码' },
|
|
avatar: { type: 'string', description: '头像URL' },
|
|
status: {
|
|
type: 'string',
|
|
enum: ['active', 'inactive', 'suspended'],
|
|
description: '用户状态'
|
|
},
|
|
createdAt: { type: 'string', format: 'date-time', description: '创建时间' },
|
|
updatedAt: { type: 'string', format: 'date-time', description: '更新时间' }
|
|
}
|
|
},
|
|
UserInput: {
|
|
type: 'object',
|
|
required: ['username', 'email', 'password'],
|
|
properties: {
|
|
username: { type: 'string', description: '用户名' },
|
|
email: { type: 'string', format: 'email', description: '邮箱地址' },
|
|
password: { type: 'string', format: 'password', description: '密码' },
|
|
phone: { type: 'string', description: '手机号码' },
|
|
avatar: { type: 'string', description: '头像URL' },
|
|
status: {
|
|
type: 'string',
|
|
enum: ['active', 'inactive', 'suspended'],
|
|
description: '用户状态'
|
|
}
|
|
}
|
|
}
|
|
};
|
|
|
|
module.exports = {
|
|
usersPaths,
|
|
usersSchemas
|
|
};
|
|
|