v1.0.0

src/app/Http/Controllers/Api/UserController.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Resources\UserResource;
+use App\Models\User;
+use Illuminate\Http\Request;
+use OpenApi\Attributes as OA;
+
+class UserController extends Controller
+{
+    #[OA\Get(
+        path: '/users',
+        summary: 'List users',
+        security: [['sanctum' => []]],
+        tags: ['Users'],
+        parameters: [
+            new OA\Parameter(
+                name: 'role',
+                description: 'Filter by role key.',
+                in: 'query',
+                schema: new OA\Schema(type: 'string', enum: ['client', 'operator', 'admin']),
+                example: 'operator',
+            ),
+            new OA\Parameter(
+                name: 'per_page',
+                description: 'Results per page (max 100).',
+                in: 'query',
+                schema: new OA\Schema(type: 'integer'),
+                example: 25,
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'OK',
+                content: new OA\JsonContent(
+                    properties: [
+                        new OA\Property('data', type: 'array', items: new OA\Items(ref: '#/components/schemas/User')),
+                    ],
+                ),
+            ),
+            new OA\Response(response: 403, description: 'Missing the users:read ability'),
+        ],
+    )]
+    public function index(Request $request)
+    {
+        $query = User::query()->with('fieldValues');
+
+        if ($request->filled('role')) {
+            $query->withRole($request->input('role'));
+        }
+
+        $perPage = min((int) $request->input('per_page', 25) ?: 25, 100);
+
+        return UserResource::collection($query->orderBy('name')->paginate($perPage));
+    }
+
+    #[OA\Get(
+        path: '/users/{user}',
+        summary: 'Get a user',
+        security: [['sanctum' => []]],
+        tags: ['Users'],
+        parameters: [
+            new OA\Parameter(name: 'user', description: 'User id.', in: 'path', required: true, schema: new OA\Schema(type: 'integer')),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'OK',
+                content: new OA\JsonContent(properties: [new OA\Property('data', ref: '#/components/schemas/User')]),
+            ),
+            new OA\Response(response: 403, description: 'Missing the users:read ability'),
+            new OA\Response(response: 404, description: 'User not found'),
+        ],
+    )]
+    public function show(User $user)
+    {
+        return new UserResource($user->load('fieldValues'));
+    }
+}