From 4694cb8c27e720e876b97ca2f2a999431577e352 Mon Sep 17 00:00:00 2001 From: Nick Zeng Date: Mon, 9 Mar 2026 09:02:21 +0800 Subject: [PATCH] update user manage --- .../app/Controller/api/v1/UserController.php | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) diff --git a/backend/app/Controller/api/v1/UserController.php b/backend/app/Controller/api/v1/UserController.php index 2305f08..d0091a1 100644 --- a/backend/app/Controller/api/v1/UserController.php +++ b/backend/app/Controller/api/v1/UserController.php @@ -10,7 +10,9 @@ use App\Model\User; use Hyperf\HttpServer\Annotation\Controller; use Hyperf\HttpServer\Annotation\Middleware; use Hyperf\HttpServer\Annotation\RequestMapping; +use OpenApi\Attributes as OA; +#[OA\Tag(name: 'Users', description: '用户管理')] #[Controller(prefix: "/api/v1/users")] class UserController extends AbstractController { @@ -19,6 +21,37 @@ class UserController extends AbstractController * * 支持分页、按 username/email 模糊搜索、按 status 精确筛选 */ + #[OA\Get( + path: '/users', + summary: '用户列表', + description: '获取用户列表，支持分页、按 username/email 模糊搜索、按 status 精确筛选', + security: [['bearerAuth' => []]], + tags: ['Users'], + parameters: [ + new OA\Parameter(name: 'page', in: 'query', required: false, schema: new OA\Schema(type: 'integer', default: 1)), + new OA\Parameter(name: 'per_page', in: 'query', required: false, schema: new OA\Schema(type: 'integer', default: 15, maximum: 100)), + new OA\Parameter(name: 'username', in: 'query', required: false, description: '用户名模糊搜索', schema: new OA\Schema(type: 'string')), + new OA\Parameter(name: 'email', in: 'query', required: false, description: '邮箱模糊搜索', schema: new OA\Schema(type: 'string')), + new OA\Parameter(name: 'status', in: 'query', required: false, description: '状态筛选（0=禁用，1=启用）', schema: new OA\Schema(type: 'integer', enum: [0, 1])), + ], + responses: [ + new OA\Response( + response: 200, + description: '获取成功', + content: new OA\JsonContent(properties: [ + new OA\Property(property: 'code', type: 'integer', example: 0), + new OA\Property(property: 'message', type: 'string', example: '获取成功'), + new OA\Property(property: 'data', properties: [ + new OA\Property(property: 'items', type: 'array', items: new OA\Items(ref: '#/components/schemas/User')), + new OA\Property(property: 'total', type: 'integer', example: 100), + new OA\Property(property: 'page', type: 'integer', example: 1), + new OA\Property(property: 'per_page', type: 'integer', example: 15), + ], type: 'object'), + ]) + ), + new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + ] + )] #[RequestMapping(path: "", methods: "GET")] #[Middleware(AuthMiddleware::class)] public function index(): array @@ -69,6 +102,37 @@ class UserController extends AbstractController /** * 创建用户 */ + #[OA\Post( + path: '/users', + summary: '创建用户', + security: [['bearerAuth' => []]], + tags: ['Users'], + requestBody: new OA\RequestBody( + required: true, + content: new OA\JsonContent( + required: ['username', 'password', 'email'], + properties: [ + new OA\Property(property: 'username', type: 'string', minLength: 3, maxLength: 20, example: 'new_user'), + new OA\Property(property: 'password', type: 'string', minLength: 6, maxLength: 32, example: 'Pass_1234'), + new OA\Property(property: 'email', type: 'string', format: 'email', maxLength: 100, example: 'new@example.com'), + new OA\Property(property: 'status', type: 'integer', enum: [0, 1], default: 1), + ] + ) + ), + responses: [ + new OA\Response( + response: 200, + description: '创建成功', + content: new OA\JsonContent(properties: [ + new OA\Property(property: 'code', type: 'integer', example: 0), + new OA\Property(property: 'message', type: 'string', example: '创建成功'), + new OA\Property(property: 'data', ref: '#/components/schemas/User'), + ]) + ), + new OA\Response(response: 400, description: '参数校验失败或唯一性冲突', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + ] + )] #[RequestMapping(path: "", methods: "POST")] #[Middleware(AuthMiddleware::class)] public function store(): \Psr\Http\Message\ResponseInterface|array @@ -175,6 +239,28 @@ class UserController extends AbstractController * * @param int $id 用户 ID */ + #[OA\Get( + path: '/users/{id}', + summary: '用户详情', + security: [['bearerAuth' => []]], + tags: ['Users'], + parameters: [ + new OA\Parameter(name: 'id', in: 'path', required: true, description: '用户 ID', schema: new OA\Schema(type: 'integer')), + ], + responses: [ + new OA\Response( + response: 200, + description: '获取成功', + content: new OA\JsonContent(properties: [ + new OA\Property(property: 'code', type: 'integer', example: 0), + new OA\Property(property: 'message', type: 'string', example: '获取成功'), + new OA\Property(property: 'data', ref: '#/components/schemas/User'), + ]) + ), + new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + new OA\Response(response: 404, description: '用户不存在', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + ] + )] #[RequestMapping(path: "{id}", methods: "GET")] #[Middleware(AuthMiddleware::class)] public function show(int $id): \Psr\Http\Message\ResponseInterface|array @@ -200,6 +286,38 @@ class UserController extends AbstractController * * @param int $id 用户 ID */ + #[OA\Put( + path: '/users/{id}', + summary: '更新用户信息', + description: '更新用户的 username、email 或 ext 字段，不支持修改密码', + security: [['bearerAuth' => []]], + tags: ['Users'], + parameters: [ + new OA\Parameter(name: 'id', in: 'path', required: true, description: '用户 ID', schema: new OA\Schema(type: 'integer')), + ], + requestBody: new OA\RequestBody( + required: true, + content: new OA\JsonContent(properties: [ + new OA\Property(property: 'username', type: 'string', minLength: 3, maxLength: 20, example: 'updated_user'), + new OA\Property(property: 'email', type: 'string', format: 'email', maxLength: 100, example: 'updated@example.com'), + new OA\Property(property: 'ext', type: 'object', nullable: true, example: ['nickname' => 'Tester']), + ]) + ), + responses: [ + new OA\Response( + response: 200, + description: '更新成功', + content: new OA\JsonContent(properties: [ + new OA\Property(property: 'code', type: 'integer', example: 0), + new OA\Property(property: 'message', type: 'string', example: '更新成功'), + new OA\Property(property: 'data', ref: '#/components/schemas/User'), + ]) + ), + new OA\Response(response: 400, description: '参数校验失败或唯一性冲突', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + new OA\Response(response: 404, description: '用户不存在', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + ] + )] #[RequestMapping(path: "{id}", methods: "PUT")] #[Middleware(AuthMiddleware::class)] public function update(int $id): \Psr\Http\Message\ResponseInterface|array @@ -319,6 +437,39 @@ class UserController extends AbstractController * * @param int $id 用户 ID */ + #[OA\Patch( + path: '/users/{id}/status', + summary: '更新用户状态', + description: '启用或禁用用户', + security: [['bearerAuth' => []]], + tags: ['Users'], + parameters: [ + new OA\Parameter(name: 'id', in: 'path', required: true, description: '用户 ID', schema: new OA\Schema(type: 'integer')), + ], + requestBody: new OA\RequestBody( + required: true, + content: new OA\JsonContent( + required: ['status'], + properties: [ + new OA\Property(property: 'status', type: 'integer', enum: [0, 1], description: '0=禁用，1=启用'), + ] + ) + ), + responses: [ + new OA\Response( + response: 200, + description: '状态更新成功', + content: new OA\JsonContent(properties: [ + new OA\Property(property: 'code', type: 'integer', example: 0), + new OA\Property(property: 'message', type: 'string', example: '状态更新成功'), + new OA\Property(property: 'data', ref: '#/components/schemas/User'), + ]) + ), + new OA\Response(response: 400, description: '参数校验失败', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + new OA\Response(response: 401, description: '未认证', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + new OA\Response(response: 404, description: '用户不存在', content: new OA\JsonContent(ref: '#/components/schemas/ErrorResponse')), + ] + )] #[RequestMapping(path: "{id}/status", methods: "PATCH")] #[Middleware(AuthMiddleware::class)] public function updateStatus(int $id): \Psr\Http\Message\ResponseInterface|array