Giới thiệu tools Swagger UI
1. Giới thiệu
Swagger là framework giúp bạn mô tả Api của mình cho developer và tester dễ dàng hiểu và thao tác thậm chí không yêu cầu vững kiến thức source code đó.
Swagger cung cấp 3 tools chính: swagger-editor, swagger-codegen, swagger-UI. Trong đó Swagger-UI là được nhiều người sử dụng nhất.
Swagger UI là một tool cho phép người dùng (developer, tester) có thể hình dung và tương tác với các tài nguyên API của dự án. Tool này sẽ tự động generates ra API documents từ file config Swagger, với cái nhìn trực quan và việc triển khai trở nên dễ dàng hơn cho phía client. Cụ thể là nó giúp sinh ra giao diện cho tài liệu. Giao diện được hiện ra rõ dàng: xem demo
2. Setup Swagger cho project
Cài đặt project laravel mới
Đây là công việc quá quen thuộc đối với các bạn làm việc với laravel, có nhiều các để cài đặt một project laravel mới như clone Laravel app từ Github về hoặc đơn giản hơn khi máy bạn đã cài composer thì chỉ cần chạy câu lệnh:
$ composer create-project laravel/laravel example-app
Cấu hình swagger
L5-Swagger là một thư viện hỗ trợ khá tốt cho toàn bộ công đoạn làm việc với Swagger bao gồm cả việc hiển thị UI và generate file config từ các API có sẵn. Document của thư viện cũng mô tả khá rõ ràng về các chức năng, và cách cài đặt.
$ composer require "darkaonline/l5-swagger:8.0"
Chú ý: phiên bản Laravel hiện tại mình cài đặt là 8.0 (mới nhất) nên cũng cần cài đặt version L5-swagger tương ứng.
Mặc định darkaonline/l5-swagger": "5.8.*" sử dụng swagger 3.0 nêu nếu bạn muốn sử dụng swagger phiên bản cũ hơn 2.0 và sử sụng @SWG thì chạy command:
composer require 'zircote/swagger-php:2.*'
Tiếp theo, Tiếp theo mình cần copy các file config của swagger ra ngoài cho dễ config
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
Sau khi command trên chạy xong, sẽ có 2 file sẽ được publish ra ngoài
- view : resources/views/vendor/l5-swagger
- config : config/l5-swagger.php
Tương ứng cũng có 2 nơi cần chú ý ở trong file config/l5-swagger.php
- Config 1: "documentations.route.api" mặc định đang là "api/documentation" đây là đường dẫn url cho swagger trong dự án của chúng ta. Bạn có thể thay đổi bất cứ url nào bạn muốn cho dễ thao tác.
- Config 2: "default.generate_always"
'generate_always' => false // mỗi lần thay đổi swagger là phải gen lại.
'generate_always' => true // swagger sẽ tự động được nạp.
Để nạp swagger chúng ta sử dụng câu lệnh:
$ php artisan l5-swagger:generate
Khi run command trên sẽ bị lỗi:
Lỗi này là do chưa tạo nơi config cho swagger. Thường sẽ tạo ở file controller.php nơi mà tất cả các request đi qua. Bạn thêm đoạn mã sau:
/**
* @OA\Info(
* version="1.0.0",
* title="Project API documents",
* description="Implementation of Swagger with in Laravel",
* @OA\Contact(
* email="admin@admin.com"
* ),
* @OA\License(
* name="Apache 2.0",
* url="http://www.apache.org/licenses/LICENSE-2.0.html"
* )
* )
*/
Có thể thấy đoạn mã trên chứa các thông tin cơ bản:
- title: tên của API.
- description: là thông tin mở rộng về API của bạn, nó có thể được viết dưới dạng multiline có hỗ trợ Markdown.
- version: chứa một chuỗi tùy ý chỉ định phiên bản API của bạn ...
3. Cấu trúc cơ bản của một document Swagger
/**
* @OA\Get(
* path="/v1/client/orders/{id}",
* operationId="getOrderId",
* tags={"Client"},
* security={
* {"Bearer": {}},
* },
* summary="Detail Order",
* description="Api Client get detail Order",
* @OA\Parameter(
* name="id",
* in="path",
* @OA\Schema(type="integer")
* ),
* @OA\Response(
* response=200,
* description="Successful operation",
* @OA\MediaType(
* mediaType="application/json",
* )
* ),
* @OA\Response(
* response=401,
* description="Unauthenticated",
* ),
* @OA\Response(
* response=403,
* description="Forbidden"
* ),
* @OA\Response(
* response=400,
* description="Bad Request"
* ),
* @OA\Response(
* response=404,
* description="not found"
* ),
* )
*/
Tài liệu swagger được viết trong commandline. Cấu trúc cơ bản gồm:
- @OA<Method-name>: định nghĩa kiểu phương thức HTTP mà chúng ta cần dùng: GET, POST, PUT...
- Path: định nghĩa đường dẫn Api
- operationId: Tên định danh của function, tương tự như trường id trong bảng dữ liệu.
- tags: Tác dụng là để gom tất cả các đầu API có trong một controller thành một nhóm giống như prefix trong route::group('prefix'=>'client')
- security: Chỉ định api này có cần xác thực hay không.
Các phương thức xác thực được hỗ trợ là:
- Phương thức xác thực HTTP: Basic, BEARER và các phương thức tương tự
- Api Key
- OAuth2
- OpenID Connect Discovery
- summary: Tóm tắt chức năng Api (Api dùng để làm gì?)
- description: Mô tả Api
- @OA\Response: là phần trả về của server: 200, 400, 401...
- @OA\Parameters: là những tham số truyền vào Api
Các parameters có nhiều kiểu được khai báo sau từ khóa in
- in body: tạo cho người dùng một input-text area, ở đó nguời dùng có thể nhập data body request (dùng chom methods Put/Path).
- in formData: như in body nhưng sử dụng cho input(dùng chom methods Put/Path).
- in path: tạo cho người dùng một input truyền thao số nhập vào lên route (dùng cho method GET).
- in query: tạo input,người dùng nhập vào và gửi lên query request (sử dụng trong method GET).
- @OA\Schema(type="integer"): định nghĩa kiểu dữ liệu nhập vào.
4. Kết luận:
Qua bài viết này mình đã chia sẻ cho bạn những kiến thức cơ bản về Swagger và cách cài đặt trong Laravel. Cuối cùng mình xin đưa ra một số nhận xét cá nhân:
Điểm mạnh
- Nó dễ cài đặt vào sử dụng, tác vụ phân rõ ràng.
- Dễ hiểu đối với developer và những người không phải dev: tester, product owner...
Điểm yếu:
- Phải đặc tả tương đối nhiều => code dài hơn gây khó chịu khi thao tác.