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

This commit is contained in:
pbao9
2026-02-15 12:31:06 +07:00
parent eb123ba97c
commit ef53ea3207
19 changed files with 3040 additions and 13433 deletions
@@ -9,6 +9,12 @@ use App\Http\Resources\Api\Client\ClientResource;
use App\Services\Api\Client\ClientAuthService;
use Illuminate\Support\Facades\Auth;
/**
* @OA\Tag(
* name="Client Authentication",
* description="API Endpoints for Client Authentication"
* )
*/
class ClientController extends Controller
{
protected $authService;
@@ -19,7 +25,59 @@ class ClientController extends Controller
}
/**
* Lấy thông tin khách hàng hiện tại
* @OA\Get(
* path="/client/me",
* operationId="getClientMe",
* tags={"Client Authentication"},
* summary="Get current client information",
* description="Returns the currently authenticated client's details",
* security={{"bearerAuth":{}}},
* @OA\Response(
* response=200,
* description="Successful operation",
* @OA\JsonContent(
* @OA\Property(property="customer", type="object",
* @OA\Property(property="fullname", type="string", example="Nguyen Van A"),
* @OA\Property(property="email", type="string", example="client@example.com"),
* @OA\Property(property="phone", type="string", example="0987654321"),
* @OA\Property(property="address", type="string", example="123 Street"),
* @OA\Property(property="city", type="string", example="Hanoi"),
* @OA\Property(property="ward", type="string", example="Ward 1"),
* @OA\Property(property="province", type="string", example="Hanoi"),
* @OA\Property(property="gender", type="string", example="Nam"),
* @OA\Property(property="date", type="string", format="date-time", example="2024-01-01 12:00:00"),
* @OA\Property(property="company", type="string", example="Company Ltd"),
* @OA\Property(property="avatar", type="string", example="/uploads/avatar.jpg"),
* @OA\Property(property="cmnd_after", type="string", example="cmnd_back.jpg"),
* @OA\Property(property="cmnd_before", type="string", example="cmnd_front.jpg"),
* @OA\Property(property="cmnd", type="string", example="123456789"),
* @OA\Property(property="fb_link", type="string", nullable=true),
* @OA\Property(property="active_2fa", type="integer", example=0),
* @OA\Property(property="off_mail_marketing", type="integer", example=0),
* @OA\Property(property="is_recharge_zalo", type="integer", example=0),
* @OA\Property(property="is_verify_telegram", type="integer", example=0)
* ),
* @OA\Property(property="credit", type="object",
* @OA\Property(property="credit", type="number", example=1000000),
* @OA\Property(property="total", type="number", example=5000000),
* @OA\Property(property="point", type="number", example=100),
* @OA\Property(property="point_used", type="integer", example=0),
* @OA\Property(property="point_total", type="number", example=100)
* ),
* @OA\Property(property="service", type="object",
* @OA\Property(property="vps", type="integer", example=2),
* @OA\Property(property="proxy", type="integer", example=0),
* @OA\Property(property="server", type="integer", example=0),
* @OA\Property(property="hosting", type="integer", example=1),
* @OA\Property(property="domain", type="integer", example=3)
* )
* )
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated"
* )
* )
*/
public function me()
{
@@ -27,7 +85,36 @@ class ClientController extends Controller
}
/**
* Đăng nhập khách hàng
* @OA\Post(
* path="/client/login",
* operationId="clientLogin",
* tags={"Client Authentication"},
* summary="Client login",
* description="Authenticate a client and return access token",
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(
* required={"email","password"},
* @OA\Property(property="email", type="string", format="email", example="client@example.com"),
* @OA\Property(property="password", type="string", format="password", example="password123")
* )
* ),
* @OA\Response(
* response=200,
* description="Login successful",
* @OA\JsonContent(
* @OA\Property(property="error", type="boolean", example=false),
* @OA\Property(property="data", type="object",
* @OA\Property(property="client", type="object"),
* @OA\Property(property="token", type="string", example="1|laravel_sanctum_token...")
* )
* )
* ),
* @OA\Response(
* response=422,
* description="Validation error"
* )
* )
*/
public function login(ClientAuthRequest $request)
{
@@ -43,7 +130,39 @@ class ClientController extends Controller
}
/**
* Đăng ký khách hàng mới
* @OA\Post(
* path="/client/register",
* operationId="clientRegister",
* tags={"Client Authentication"},
* summary="Client registration",
* description="Register a new client account",
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(
* required={"fullname","phone","email","password","password_confirmation"},
* @OA\Property(property="fullname", type="string", example="Nguyen Van A"),
* @OA\Property(property="phone", type="string", example="0987654321"),
* @OA\Property(property="email", type="string", format="email", example="client@example.com"),
* @OA\Property(property="password", type="string", format="password", example="password123"),
* @OA\Property(property="password_confirmation", type="string", format="password", example="password123")
* )
* ),
* @OA\Response(
* response=200,
* description="Registration successful",
* @OA\JsonContent(
* @OA\Property(property="error", type="boolean", example=false),
* @OA\Property(property="data", type="object",
* @OA\Property(property="client", type="object"),
* @OA\Property(property="token", type="string", example="1|laravel_sanctum_token...")
* )
* )
* ),
* @OA\Response(
* response=422,
* description="Validation error"
* )
* )
*/
public function register(ClientRegisterRequest $request)
{
@@ -59,7 +178,26 @@ class ClientController extends Controller
}
/**
* Đăng xuất khách hàng
* @OA\Post(
* path="/client/logout",
* operationId="clientLogout",
* tags={"Client Authentication"},
* summary="Client logout",
* description="Logout the currently authenticated client",
* security={{"bearerAuth":{}}},
* @OA\Response(
* response=200,
* description="Logout successful",
* @OA\JsonContent(
* @OA\Property(property="error", type="boolean", example=false),
* @OA\Property(property="message", type="string", example="Đã đăng xuất thành công.")
* )
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated"
* )
* )
*/
public function logout()
{
@@ -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);
}
}
}
}
@@ -23,6 +23,12 @@ use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Validator;
/**
* @OA\Tag(
* name="Services",
* description="API Endpoints for Services/Products"
* )
*/
class ServiceController extends Controller
{
protected $serviceService;
@@ -37,6 +43,56 @@ class ServiceController extends Controller
$this->serviceRepository = $serviceRepository;
}
/**
* @OA\Get(
* path="/services/get-list",
* operationId="getServiceList",
* tags={"Services"},
* summary="Get list of services",
* description="Returns a paginated list of active services/products",
* @OA\Parameter(
* name="limit",
* in="query",
* description="Number of items per page",
* required=false,
* @OA\Schema(type="integer", default=10)
* ),
* @OA\Response(
* response=200,
* description="Successful operation",
* @OA\JsonContent(
* @OA\Property(property="error", type="boolean", example=false),
* @OA\Property(property="message", type="string", example="Lấy dữ liệu thành công"),
* @OA\Property(property="page_type", type="string", example="service"),
* @OA\Property(property="data", type="array", @OA\Items(
* @OA\Property(property="uuid", type="string", example="550e8400-e29b-41d4-a716-446655440000"),
* @OA\Property(property="name", type="string", example="Cloud VPS Basic"),
* @OA\Property(property="slug", type="string", example="cloud-vps-basic"),
* @OA\Property(property="short_description", type="string", example="Basic VPS plan"),
* @OA\Property(property="description", type="string"),
* @OA\Property(property="thumbnail", type="string", example="https://example.com/images/vps.jpg"),
* @OA\Property(property="product_type", type="string", example="vps"),
* @OA\Property(property="specs", type="object",
* @OA\Property(property="cpu", type="integer", example=2),
* @OA\Property(property="ram", type="integer", example=4),
* @OA\Property(property="disk", type="integer", example=50),
* @OA\Property(property="bandwidth", type="integer", example=1000),
* @OA\Property(property="gpu", type="string", nullable=true)
* ),
* @OA\Property(property="stock", type="integer", example=100),
* @OA\Property(property="price", type="number", example=299000),
* @OA\Property(property="price_sale", type="number", example=199000),
* @OA\Property(property="pricing", type="object"),
* @OA\Property(property="pricing_sale", type="object"),
* @OA\Property(property="group", type="string", example="VPS"),
* @OA\Property(property="os", type="array", @OA\Items(
* @OA\Property(property="group", type="string", example="Ubuntu")
* ))
* ))
* )
* )
* )
*/
public function getService(Request $request)
{
$limit = $request->get('limit', 10);
@@ -49,6 +105,63 @@ class ServiceController extends Controller
]);
}
/**
* @OA\Get(
* path="/services/{slug}",
* operationId="getServiceDetail",
* tags={"Services"},
* summary="Get service details",
* description="Returns detailed information about a specific service/product",
* @OA\Parameter(
* name="slug",
* in="path",
* description="Service slug",
* required=true,
* @OA\Schema(type="string")
* ),
* @OA\Response(
* response=200,
* description="Successful operation",
* @OA\JsonContent(
* @OA\Property(property="error", type="boolean", example=false),
* @OA\Property(property="message", type="string", example="Lấy dữ liệu thành công"),
* @OA\Property(property="page_type", type="string", example="service"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="uuid", type="string", example="550e8400-e29b-41d4-a716-446655440000"),
* @OA\Property(property="name", type="string", example="Cloud VPS Basic"),
* @OA\Property(property="slug", type="string", example="cloud-vps-basic"),
* @OA\Property(property="short_description", type="string", example="Basic VPS plan"),
* @OA\Property(property="description", type="string"),
* @OA\Property(property="thumbnail", type="string", example="https://example.com/images/vps.jpg"),
* @OA\Property(property="product_type", type="string", example="vps"),
* @OA\Property(property="specs", type="object",
* @OA\Property(property="cpu", type="integer", example=2),
* @OA\Property(property="ram", type="integer", example=4),
* @OA\Property(property="disk", type="integer", example=50),
* @OA\Property(property="bandwidth", type="integer", example=1000),
* @OA\Property(property="gpu", type="string", nullable=true)
* ),
* @OA\Property(property="stock", type="integer", example=100),
* @OA\Property(property="price", type="number", example=299000),
* @OA\Property(property="price_sale", type="number", example=199000),
* @OA\Property(property="group", type="string", example="VPS"),
* @OA\Property(property="os", type="array", @OA\Items(
* @OA\Property(property="name", type="string", example="Ubuntu"),
* @OA\Property(property="thumbnail", type="string"),
* @OA\Property(property="versions", type="array", @OA\Items(
* @OA\Property(property="version", type="string", example="22.04"),
* @OA\Property(property="name", type="string", example="Ubuntu 22.04 LTS")
* ))
* ))
* )
* )
* ),
* @OA\Response(
* response=404,
* description="Service not found"
* )
* )
*/
public function getDetailService(Product $product)
{
$product->load([
@@ -5,8 +5,32 @@ namespace App\Http\Controllers\Api\Setting;
use App\Http\Controllers\Controller;
use App\Models\Setting;
/**
* @OA\Tag(
* name="Settings",
* description="API Endpoints for Application Settings"
* )
*/
class SettingController extends Controller
{
/**
* @OA\Get(
* path="/setting",
* operationId="getSetting",
* tags={"Settings"},
* summary="Get application settings",
* description="Returns the application settings",
* @OA\Response(
* response=200,
* description="Successful operation",
* @OA\JsonContent(
* @OA\Property(property="data", type="object"),
* @OA\Property(property="message", type="string", example="Get setting successfully"),
* @OA\Property(property="error", type="boolean", example=false)
* )
* )
* )
*/
public function getSetting()
{
$setting = Setting::where('key', 'setting')->first();
+26
View File
@@ -8,6 +8,32 @@ use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Routing\Controller as BaseController;
/**
* @OA\Info(
* version="1.0.0",
* title="Portal API",
* description="API Documentation for Portal Application",
* @OA\Contact(
* email="admin@portal.com"
* ),
* @OA\License(
* name="MIT",
* url="https://opensource.org/licenses/MIT"
* )
* )
*
* @OA\Server(
* url="/api/v1",
* description="API Server"
* )
*
* @OA\SecurityScheme(
* securityScheme="bearerAuth",
* type="http",
* scheme="bearer",
* bearerFormat="JWT"
* )
*/
class Controller extends BaseController
{
use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
@@ -124,7 +124,7 @@ class VirtualMachineController extends Controller
{
$query = $this->virtualMachineRepository->filter(
$request->all(),
['datacenter'],
['datacenter', 'host'],
[],
['*'],
true
@@ -151,6 +151,9 @@ class VirtualMachineController extends Controller
->editColumn('datacenter.name', function ($d) {
return $d->datacenter ? $d->datacenter->name . ' - ' . $d->datacenter->datacenter_id : 'N/A';
})
->editColumn('host.name', function ($d) {
return $d->host ? $d->host->name . ' - ' . $d->host->host_id : 'N/A';
})
->rawColumns(['action', 'power_state'])
->make(true);
}