feat: Integrate L5-Swagger for API documentation and enhance VM synchronization to include host-level details.

app/Http/Controllers/Api/Service/OrderController.php

@@ -10,6 +10,12 @@ use App\Services\Api\Order\OrderService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 
+/**
+ * @OA\Tag(
+ *     name="Orders",
+ *     description="API Endpoints for Order Management"
+ * )
+ */
 class OrderController extends Controller
 {
     public function __construct(
@@ -17,6 +23,107 @@ class OrderController extends Controller
         protected OrderRepository $orderRepo
     ) {}
 
+    /**
+     * @OA\Get(
+     *     path="/orders",
+     *     operationId="getOrdersList",
+     *     tags={"Orders"},
+     *     summary="Get list of orders",
+     *     description="Returns a list of orders for the authenticated customer",
+     *     security={{"bearerAuth":{}}},
+     *     @OA\Parameter(
+     *         name="total_price",
+     *         in="query",
+     *         description="Filter by total price",
+     *         required=false,
+     *         @OA\Schema(type="number")
+     *     ),
+     *     @OA\Parameter(
+     *         name="pending",
+     *         in="query",
+     *         description="Filter by pending status",
+     *         required=false,
+     *         @OA\Schema(type="boolean")
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="Successful operation",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="success", type="boolean", example=true),
+     *             @OA\Property(property="data", type="array", @OA\Items(type="object"))
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthenticated"
+     *     )
+     * )
+     */
+    public function getList(Request $request): JsonResponse
+    {
+        try {
+            $customer = $request->user();
+
+            $filters = [
+                'total_price' => $request->query('total_price'),
+                'pending' => $request->query('pending')
+            ];
+
+            $orders = $this->orderRepo->getOrders($customer->id, $filters);
+
+            return response()->json([
+                'success' => true,
+                'data' => $orders
+            ]);
+        } catch (\Exception $e) {
+            return response()->json([
+                'success' => false,
+                'message' => $e->getMessage()
+            ], 400);
+        }
+    }
+
+    /**
+     * @OA\Post(
+     *     path="/orders",
+     *     operationId="storeOrder",
+     *     tags={"Orders"},
+     *     summary="Create a new order",
+     *     description="Create a new order for a product",
+     *     security={{"bearerAuth":{}}},
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"product_id","billing_cycle"},
+     *             @OA\Property(property="product_id", type="string", example="550e8400-e29b-41d4-a716-446655440000", description="Product UUID"),
+     *             @OA\Property(property="billing_cycle", type="string", example="monthly", enum={"monthly", "quarterly", "semi_annually", "annually", "biennially"}),
+     *             @OA\Property(property="server_name", type="string", example="My VPS Server"),
+     *             @OA\Property(property="os_id", type="integer", example=1, description="Operating System ID"),
+     *             @OA\Property(property="addons", type="array", @OA\Items(
+     *                 @OA\Property(property="addon_id", type="integer", example=1),
+     *                 @OA\Property(property="qty", type="integer", example=1)
+     *             ))
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=201,
+     *         description="Order created successfully",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="success", type="boolean", example=true),
+     *             @OA\Property(property="data", type="object"),
+     *             @OA\Property(property="message", type="string", example="Tạo đơn hàng thành công")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthenticated"
+     *     ),
+     *     @OA\Response(
+     *         response=422,
+     *         description="Validation error"
+     *     )
+     * )
+     */
     public function storeOrder(StoreOrderRequest $request): JsonResponse
     {
         try {
@@ -39,7 +146,7 @@ class OrderController extends Controller
             if (!$customer) {
                 return response()->json([
                     'success' => false,
-                    'message' => 'Người dùng chưa đăng nhập hoặc phiên đăng nhập hết hạn.'
+                    'message' => 'Ngườ;i dùng chưa đăng nhập hoặc phiên đăng nhập hết hạn.'
                 ], 401);
             }
 
@@ -59,6 +166,50 @@ class OrderController extends Controller
         }
     }
 
+    /**
+     * @OA\Post(
+     *     path="/orders/{id}/pay",
+     *     operationId="payOrder",
+     *     tags={"Orders"},
+     *     summary="Pay for an order",
+     *     description="Process payment for a specific order",
+     *     security={{"bearerAuth":{}}},
+     *     @OA\Parameter(
+     *         name="id",
+     *         in="path",
+     *         description="Order ID",
+     *         required=true,
+     *         @OA\Schema(type="integer")
+     *     ),
+     *     @OA\RequestBody(
+     *         required=true,
+     *         @OA\JsonContent(
+     *             required={"payment_method"},
+     *             @OA\Property(property="payment_method", type="string", example="credit", enum={"credit", "vnpay", "momo", "bank_transfer"})
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="Payment successful",
+     *         @OA\JsonContent(
+     *             @OA\Property(property="success", type="boolean", example=true),
+     *             @OA\Property(property="message", type="string", example="Thanh toán thành công")
+     *         )
+     *     ),
+     *     @OA\Response(
+     *         response=401,
+     *         description="Unauthenticated"
+     *     ),
+     *     @OA\Response(
+     *         response=403,
+     *         description="Forbidden - Not your order"
+     *     ),
+     *     @OA\Response(
+     *         response=404,
+     *         description="Order not found"
+     *     )
+     * )
+     */
     public function payOrder(int $id, PayOrderRequest $request): JsonResponse
     {
         try {
@@ -86,28 +237,4 @@ class OrderController extends Controller
             ], 400);
         }
     }
-
-    public function getList(Request $request): JsonResponse
-    {
-        try {
-            $customer = $request->user();
-
-            $filters = [
-                'total_price' => $request->query('total_price'),
-                'pending' => $request->query('pending')
-            ];
-
-            $orders = $this->orderRepo->getOrders($customer->id, $filters);
-
-            return response()->json([
-                'success' => true,
-                'data' => $orders
-            ]);
-        } catch (\Exception $e) {
-            return response()->json([
-                'success' => false,
-                'message' => $e->getMessage()
-            ], 400);
-        }
-    }
-}
+}