Feature/swagger api docs

app/Http/Controllers/Admin/UserController.php

@@ -9,13 +9,94 @@
 
 class UserController extends Controller
 {
+    /**
+     * @OA\Get(
+     *     path="/api/users",
+     *     tags={"Users"},
+     *     summary="Get all users with roles",
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="List of users",
+     *
+     *         @OA\JsonContent(
+     *             type="object",
+     *
+     *             @OA\Property(
+     *                 property="data",
+     *                 type="array",
+     *
+     *                 @OA\Items(
+     *                     type="object",
+     *
+     *                     @OA\Property(property="id", type="integer", example=1),
+     *                     @OA\Property(property="name", type="string", example="Shubham Belwal"),
+     *                     @OA\Property(property="email", type="string", example="[email protected]"),
+     *                     @OA\Property(
+     *                         property="roles",
+     *                         type="array",
+     *
+     *                         @OA\Items(
+     *                             type="object",
+     *
+     *                             @OA\Property(property="id", type="integer", example=1),
+     *                             @OA\Property(property="name", type="string", example="admin")
+     *                         )
+     *                     )
+     *                 )
+     *             )
+     *         )
+     *     )
+     * )
+     */
     public function index()
     {
         $users = User::with('roles')->paginate(10);
 
         return response()->json($users);
     }
 
+    /**
+     * @OA\Put(
+     *     path="/api/users/{id}/roles",
+     *     tags={"Users"},
+     *     summary="Update user roles",
+     *
+     *     @OA\Parameter(
+     *         name="id",
+     *         in="path",
+     *         required=true,
+     *         description="User ID",
+     *
+     *         @OA\Schema(type="integer")
+     *     ),
+     *
+     *     @OA\RequestBody(
+     *         required=true,
+     *
+     *         @OA\JsonContent(
+     *             required={"roles"},
+     *
+     *             @OA\Property(
+     *                 property="roles",
+     *                 type="array",
+     *
+     *                 @OA\Items(type="string", example="admin")
+     *             )
+     *         )
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="Roles updated successfully",
+     *
+     *         @OA\JsonContent(
+     *
+     *             @OA\Property(property="message", type="string", example="Roles updated successfully")
+     *         )
+     *     )
+     * )
+     */
     public function updateRoles(Request $request, User $user)
     {
         $request->validate([
@@ -28,13 +109,62 @@ public function updateRoles(Request $request, User $user)
         return response()->json(['message' => 'Roles updated successfully']);
     }
 
+    /**
+     * @OA\Get(
+     *     path="/api/roles",
+     *     tags={"Users"},
+     *     summary="Get all available roles",
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="List of roles",
+     *
+     *         @OA\JsonContent(
+     *             type="array",
+     *
+     *             @OA\Items(
+     *                 type="object",
+     *
+     *                 @OA\Property(property="id", type="integer", example=1),
+     *                 @OA\Property(property="name", type="string", example="editor")
+     *             )
+     *         )
+     *     )
+     * )
+     */
     public function getRoles()
     {
         $roles = Role::all();
 
         return response()->json($roles);
     }
 
+    /**
+     * @OA\Delete(
+     *     path="/api/users/{id}",
+     *     tags={"Users"},
+     *     summary="Delete a user",
+     *
+     *     @OA\Parameter(
+     *         name="id",
+     *         in="path",
+     *         required=true,
+     *         description="User ID",
+     *
+     *         @OA\Schema(type="integer")
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="User deleted successfully",
+     *
+     *         @OA\JsonContent(
+     *
+     *             @OA\Property(property="message", type="string", example="User deleted successfully")
+     *         )
+     *     )
+     * )
+     */
     public function destroy(User $user)
     {
         $user->delete();

app/Http/Controllers/SwaggerController.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Http\Controllers;
+
+/**
+ * @OA\Info(
+ *     title="Your Laravel API",
+ *     version="1.0.0",
+ *     description="Swagger documentation for Laravel APIs",
+ *
+ *     @OA\Contact(
+ *         email="[email protected]"
+ *     )
+ * )
+ *
+ * @OA\Server(
+ *     url="http://localhost:8000",
+ *     description="Local API Server"
+ * )
+ */
+class SwaggerController {}

composer.json

@@ -11,6 +11,7 @@
     "license": "MIT",
     "require": {
         "php": "^8.2",
+        "darkaonline/l5-swagger": "^9.0",
         "laravel/framework": "^12.0",
         "laravel/sanctum": "^4.0",
         "laravel/tinker": "^2.10.1",