Đăng bởi Admin 1 month ago 0 bình luận

Swagger là một công cụ mạnh mẽ giúp mô tả và kiểm thử API, và khi kết hợp với Laravel, nó sẽ giúp bạn tự động tạo tài liệu API từ các chú thích trong mã nguồn. Trong bài viết này, chúng ta sẽ tạo một API PUT trong Laravel để cập nhật thông tin khách hàng và mô tả nó bằng Swagger.

Bước 1: Tạo Controller

Đầu tiên, bạn cần tạo một controller để xử lý yêu cầu PUT. Chúng ta sẽ tạo một controller có tên CustomerController và thêm phương thức update() để nhận và cập nhật thông tin khách hàng.

php artisan make:controller CustomerController

Sau khi tạo xong, mở file app/Http/Controllers/CustomerController.php và thêm phương thức update() như sau:

<?php

namespace App\Http\Controllers;

use App\Models\Customer;
use Illuminate\Http\Request;

class CustomerController extends Controller
{
    /**
     * @OA\Put(
     *     path="/api/customers/{id}",
     *     summary="Cập nhật thông tin khách hàng",
     *     tags={"Customers"},
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         description="ID của khách hàng",
     *         @OA\Schema(type="integer")
     *     ),
     *     @OA\RequestBody(
     *         required=true,
     *         @OA\MediaType(
     *             mediaType="application/json",
     *             @OA\Schema(
     *                 type="object",
     *                 required={"name", "email"},
     *                 @OA\Property(property="name", type="string", example="Jane Doe"),
     *                 @OA\Property(property="email", type="string", format="email", example="jane.doe@example.com")
     *             )
     *         )
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="Thông tin khách hàng được cập nhật thành công",
     *         @OA\JsonContent(
     *             @OA\Property(property="message", type="string", example="Customer updated successfully"),
     *             @OA\Property(property="customer", type="object", ref="#/components/schemas/Customer")
     *         )
     *     ),
     *     @OA\Response(response=400, description="Dữ liệu đầu vào không hợp lệ"),
     *     @OA\Response(response=404, description="Khách hàng không tìm thấy")
     * )
     */
    public function update(Request $request, $id)
    {
        $customer = Customer::find($id);

        if (!$customer) {
            return response()->json(['message' => 'Customer not found'], 404);
        }

        $validated = $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:customers,email,' . $id,
        ]);

        $customer->update($validated);

        return response()->json([
            'message' => 'Customer updated successfully',
            'customer' => $customer
        ]);
    }
}

Trong đoạn mã trên, chúng ta sử dụng chú thích Swagger @OA\Put để mô tả phương thức PUT, @OA\Parameter để mô tả tham số id (ID của khách hàng), @OA\RequestBody để mô tả dữ liệu yêu cầu, và @OA\Response để mô tả phản hồi API.

Bước 2: Định Nghĩa Route

Mở file routes/api.php và thêm route cho API PUT:

use App\Http\Controllers\CustomerController;

Route::put('/customers/{id}', [CustomerController::class, 'update']);

Route này sẽ liên kết với phương thức update() trong CustomerController.

Bước 3: Tạo Tài Liệu Swagger

Sau khi bạn đã tạo API PUT, bạn cần tạo tài liệu Swagger bằng cách sử dụng các chú thích trong mã nguồn. Package swagger-php sẽ tự động quét các chú thích này và tạo ra tài liệu Swagger.

Để tạo tài liệu Swagger, bạn chỉ cần chạy lệnh sau:

php artisan l5-swagger:generate

Lệnh này sẽ quét toàn bộ các chú thích Swagger trong mã nguồn của bạn và tạo tài liệu Swagger.

Bước 4: Truy Cập Tài Liệu Swagger

Sau khi tài liệu Swagger được tạo, bạn có thể truy cập tài liệu này thông qua đường dẫn sau:

http://localhost:8000/docs

Trang này sẽ hiển thị tài liệu Swagger của bạn, cho phép bạn kiểm thử API PUT trực tiếp từ giao diện Swagger.

Bước 5: Kiểm Tra API PUT

Để kiểm tra API PUT, bạn có thể sử dụng Postman hoặc gửi yêu cầu PUT tới:

http://localhost:8000/api/customers/{id}

Trong đó {id} là ID của khách hàng bạn muốn cập nhật. Dữ liệu yêu cầu phải có dạng JSON, ví dụ:

{
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
}

Nếu khách hàng với ID này tồn tại, bạn sẽ nhận được phản hồi JSON như sau:

{
    "message": "Customer updated successfully",
    "customer": {
        "id": 1,
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "created_at": "2024-12-25T12:00:00",
        "updated_at": "2024-12-25T12:00:00"
    }
}

Nếu khách hàng không tồn tại, bạn sẽ nhận được lỗi:

{
    "message": "Customer not found"
}

Kết Luận

Trong bài viết này, chúng ta đã tạo một API PUT trong Laravel để cập nhật thông tin khách hàng và mô tả nó bằng Swagger. Việc sử dụng Swagger giúp bạn dễ dàng tự động hóa tài liệu API và kiểm thử API trực tiếp từ giao diện Swagger. Điều này sẽ giúp bạn phát triển và duy trì API nhanh chóng và hiệu quả hơn.

Bạn có thể mở rộng ví dụ này với các API khác như GET, POST, DELETE, hoặc các tính năng phức tạp hơn như xác thực người dùng, xử lý lỗi, v.v.

Tags: