feat: Create API Documentation with simple authentication routes and global error handling on top of global api responder

Author: d-arsya

app/Exceptions/NotAccept.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Exceptions;
+
+use App\Traits\ApiResponder;
+use Exception;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+
+class NotAccept extends Exception
+{
+    use ApiResponder;
+
+    public function __invoke(AccessDeniedHttpException $e, Request $request)
+    {
+        return $this->error(null, 'Unauthorized', 403);
+    }
+}

app/Exceptions/NotFound.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Exceptions;
+
+use App\Traits\ApiResponder;
+use Exception;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+class NotFound extends Exception
+{
+    use ApiResponder;
+
+    public function __invoke(NotFoundHttpException $e, Request $request)
+    {
+        return $this->error(null, 'Item not found', 404);
+    }
+}

app/Http/Controllers/AuthController.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Exceptions\NotAccept;
+use App\Http\Requests\LoginRequest;
+use App\Http\Requests\RegisterRequest;
+use App\Http\Resources\UserResource;
+use App\Models\User;
+use App\Traits\ApiResponder;
+use Dedoc\Scramble\Attributes\Group;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+
+class AuthController extends Controller
+{
+    use ApiResponder;
+
+    /**
+     * Register
+     *
+     * Register new user
+     */
+    #[Group('Authentication')]
+    public function register(RegisterRequest $request)
+    {
+        $user = User::create($request->all());
+        return $this->created(new UserResource($user), 'Success to register');
+    }
+
+    /**
+     * Login
+     *
+     * Login using existing user credential
+     */
+    #[Group('Authentication')]
+    public function login(LoginRequest $request)
+    {
+        $credentials = $request->all();
+        $token = Auth::attempt($credentials);
+        if (!$token) throw new NotAccept;
+        return $this->success([
+            'token' => $token,
+            'expiresIn' => now()
+                ->addMinutes(Auth::factory()->getTTL())
+                ->setTimezone(config('app.timezone')),
+        ]);
+    }
+
+    /**
+     * User Profile
+     *
+     * Get logged in user profile
+     */
+    #[Group('User')]
+    public function profile()
+    {
+        return $this->success(new UserResource(Auth::user()));
+    }
+}

app/Http/Requests/LoginRequest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class LoginRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'email' => 'string|max:50|min:8|email|exists:users,email',
+            'password' => 'string|min:8'
+        ];
+    }
+}

app/Http/Requests/RegisterRequest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class RegisterRequest extends FormRequest
+{
+    /**
+     * Determine if the user is authorized to make this request.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'email' => 'string|max:50|min:8|email|unique:users,email',
+            'password' => 'string|min:8'
+        ];
+    }
+}

app/Http/Resources/UserResource.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class UserResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return parent::toArray($request);
+    }
+}

app/Models/User.php

@@ -2,47 +2,29 @@
 
 namespace App\Models;
 
-// use Illuminate\Contracts\Auth\MustVerifyEmail;
-use Illuminate\Database\Eloquent\Factories\HasFactory;
+use App\Observers\UserObserver;
+use Illuminate\Database\Eloquent\Attributes\ObservedBy;
 use Illuminate\Foundation\Auth\User as Authenticatable;
-use Illuminate\Notifications\Notifiable;
+use Tymon\JWTAuth\Contracts\JWTSubject;
 
-class User extends Authenticatable
+#[ObservedBy([UserObserver::class])]
+class User extends Authenticatable implements JWTSubject
 {
-    /** @use HasFactory<\Database\Factories\UserFactory> */
-    use HasFactory, Notifiable;
+    protected $guarded = [];
 
-    /**
-     * The attributes that are mass assignable.
-     *
-     * @var list<string>
-     */
-    protected $fillable = [
-        'name',
-        'email',
-        'password',
-    ];
-
-    /**
-     * The attributes that should be hidden for serialization.
-     *
-     * @var list<string>
-     */
     protected $hidden = [
         'password',
-        'remember_token',
     ];
+    protected $casts = [
+        'password' => 'hashed'
+    ];
+    public function getJWTIdentifier()
+    {
+        return $this->getKey();
+    }
 
-    /**
-     * Get the attributes that should be cast.
-     *
-     * @return array<string, string>
-     */
-    protected function casts(): array
+    public function getJWTCustomClaims()
     {
-        return [
-            'email_verified_at' => 'datetime',
-            'password' => 'hashed',
-        ];
+        return [];
     }
 }

app/Observers/UserObserver.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace App\Observers;
+
+use App\Models\User;
+
+class UserObserver
+{
+    public function creating(User $user)
+    {
+        $user->username = strstr($user->email, '@', true);
+    }
+}

app/Providers/AppServiceProvider.php

@@ -2,6 +2,9 @@
 
 namespace App\Providers;
 
+use Dedoc\Scramble\Scramble;
+use Dedoc\Scramble\Support\Generator\OpenApi;
+use Dedoc\Scramble\Support\Generator\SecurityScheme;
 use Illuminate\Support\ServiceProvider;
 
 class AppServiceProvider extends ServiceProvider
@@ -11,14 +14,19 @@ class AppServiceProvider extends ServiceProvider
      */
     public function register(): void
     {
-        //
+        Scramble::ignoreDefaultRoutes();
     }
 
     /**
      * Bootstrap any application services.
      */
     public function boot(): void
     {
-        //
+        Scramble::configure()
+            ->withDocumentTransformers(function (OpenApi $openApi) {
+                $openApi->secure(
+                    SecurityScheme::http('bearer')
+                );
+            });
     }
 }

app/Traits/ApiResponder.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Traits;
+
+trait ApiResponder
+{
+    protected function success($data, $message = 'Success', $status = 200)
+    {
+        return response()->json([
+            'success' => true,
+            'message' => $message,
+            'data' => $data,
+        ], $status);
+    }
+
+    protected function delete($data = null, $message = 'Deleted', $status = 200)
+    {
+        return response()->json([
+            'success' => true,
+            'message' => $message,
+            'data' => $data,
+        ], $status);
+    }
+
+    protected function created($data, $message = 'Success')
+    {
+        return response()->json([
+            'success' => true,
+            'message' => $message,
+            'data' => $data,
+        ], 201);
+    }
+
+    protected function error($errors = [], $message, $status = 400)
+    {
+        return response()->json([
+            'success' => false,
+            'message' => $message,
+            'data' => $errors,
+        ], $status);
+    }
+}