L5 Swagger – REST APIs trở lên dễ dàng hơn bao giờ hết

Vẫn là L5 nhưng lần này là L5 Swagger chứ không phải L5 Repository anh em nhé. Chắc hẳn anh em Dev Backend rất ngán ngẩm việc làm docs API. Nó giúp anh em check API cực kì thuận tiện, cũng ít bị tester kêu gào bên tai. Swagger là công cụ generate api documment một cách dễ dàng thuận tiện

L5 Swagger là sản phẩm của nhà DarkaOnLine. Anh em tham khảo Github nhé. Xem tại đây

Swagger UI: giao diện dễ nhìn, tường minh, được sinh ra từ file config chuẩn OpenAPI. Có thể test API trực tiếp mà chúng ta không cần dùng đến công cụ kinh điển là postman nữa

Cài đặt

Chạy command

composer require "darkaonline/l5-swagger"

Với các phiên bản laravel thấp hơn thì chúng ta cũng cần phải cài bản swagger tương ứng. Khá bất cập nhưng cũng không phải vấn đề lớn so với ưu điểm của nó đúng không ạ

Đối với Laravel >=5.5 thì không cần thêm L5SwaggerServiceProvider vào config.

Cấu hình

Với phiên bản >= 6

Chúng ta cần publish L5-Swagger vào dự án của mình. Chạy command:

$ php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
$ php artisan l5-swagger:generate

Đối với phiên bản < 5.5 thì chúng ta cần chạy nhiều hơn

Tiếp theo, để tiến hành sử dụng thì chúng ta thêm Swagger api documentation  trong Controller nhé:

Function xử lý ngay bên dưới:

Khi viết xong 1 function thì chúng ta sẽ generate lại file

php artisan l5-swagger:generate

Nếu không muốn mỗi lần thay đổi code mà phải generate file thì hãy config trong .env L5_SWAGGER_GENERATE_ALWAYS=true

Giờ thì chúng ta có thể truy cập http://127.0.0.1:8000/api/documentation. Do mình đang chạy artisan serve nên dùng host http://127.0.0.1:8000. Bạn có thể đổi sang host local của bạn nhé.

Click Try it out -> Excute

Ta có kết quả

Không khác gì trên postman đúng không ạ

Trên đây là bài chia sẻ của mình về L5-Swagger trong Laravel. Các bạn cài đặt về thử và ứng dụng vào dự án của mình nhé.

Một vài điểm mình nhận thấy:

Điểm mạnh:
– Dễ dàng cài đặt và sử dụng. Tài liệu đầy đủ.
– Tác vụ trong L5 Swagger được phân chia rõ ràng.
– Phần mô tả trong comment tường minh và khá sát với file config.
– Không cần phải dùng đến công cụ thứ 3 để test API như postman nữa
Điểm yếu:
– Do phải đặt tả tương đối nhiều trong comment sẽ làm code bị to ra gây khó chịu trong quá trình dev và đọc code.
– Do đoạn code trong config không tự format được nên dễ dính lỗi sai chính tả
– Generate khá nhiều file config