Buzz
Swagger là gì? Đối với những ai yêu thích công nghệ, thuật ngữ Swagger có lẽ đã trở nên quen thuộc. Tuy nhiên, với những người không trong ngành, có thể dễ dàng nhầm lẫn Swagger với một khẩu hiệu mà giới trẻ thường dùng. Vậy, Swagger mang ý nghĩa gì? Chức năng của Swagger là gì? Hãy cùng Mytour khám phá bài viết dưới đây để hiểu rõ hơn về Swagger.
Swagger là gì? Làm thế nào để hiểu đúng về Swagger?
Công cụ hỗ trợ thiết kế APIOpen API là gì?
Open API, hay còn gọi là Open API Specification, là một định dạng được sử dụng để mô tả các API cho các dịch vụ REST hiện nay. Chỉ với một tệp Open API, bạn có thể mô tả toàn bộ chức năng của API. Nội dung mô tả sẽ bao gồm:
- Tạo điều kiện thuận lợi cho người dùng hoặc thiết bị đầu cuối và các hoạt động của họ.
- Cung cấp chi tiết về các tham số đầu vào và đầu ra của mỗi hoạt động. Hiển thị các phương thức xác thực đang được sử dụng.
- Cung cấp thông tin liên hệ với chứng chỉ và các điều khoản liên quan khác.
Hiện nay, các thông số kỹ thuật API có thể được viết bằng các định dạng như JSON hoặc YAML. Đây là hai kiểu định dạng thuận lợi cho cả người dùng lẫn hệ thống máy tính nhờ vào tính dễ đọc và sử dụng của chúng.
Khái niệm Swagger là gì?
Phần mềm mã nguồn mở SwaggerVới tầm quan trọng của Open API, yếu tố nào đã hình thành nên bộ mô tả này? Swagger được xem là một công cụ mã nguồn mở nhằm tạo ra các đặc điểm của Open API Specifications. Công cụ này hỗ trợ bạn trong việc sáng tạo nội dung, phát triển tài liệu cũng như sử dụng các Rest APIs.
Đối với các lập trình viên, khi sử dụng Swagger, họ sẽ nhận được sự hỗ trợ từ 3 công cụ chính như sau:
- Công cụ Swagger Editor: Dùng để thiết kế và xây dựng APIs theo cách hoàn toàn mới hoặc chỉnh sửa các APIs hiện có bằng cách sử dụng một tệp cấu hình.
- Công cụ Swagger Codegen: Hiệu quả trong việc tạo mã (code) từ các tệp cấu hình đã có sẵn.
- Công cụ Swagger UI: Ứng dụng cho phép tạo ra các tệp HTML, CSS,… từ một tệp cấu hình.
Trong số các công cụ đã nêu, Swagger UI nổi bật nhất hiện nay. Công cụ này có chức năng tuyệt vời trong việc tạo ra giao diện cho các tài liệu dựa trên tệp cấu hình, áp dụng theo tiêu chuẩn của Open API. Giao diện được tạo ra từ công cụ này thường rất dễ hiểu và rõ ràng, được trình bày một cách cụ thể nhất cho các nhà phát triển. Điều này mang lại nhiều lợi ích cho người dùng và các chuyên viên lập trình trong quá trình nghiên cứu và ứng dụng.
Mỗi API sử dụng trong quá trình này sẽ cung cấp thông tin chi tiết về nguồn vào và nguồn ra. Đặc biệt, chúng ta có thể nhập dữ liệu vào để kiểm tra xem các kết quả có khả quan và chính xác hay không.
Cấu trúc cơ bản của Swagger là gì?
Cấu trúc của Swagger bao gồm những gì?Hiểu rõ các cấu trúc cơ bản của Swagger sẽ giúp lập trình viên nắm bắt tốt hơn bộ công cụ này và áp dụng một cách linh hoạt trong các tình huống cụ thể.
Metadata hay Info
Hầu hết các Open API Specifications đều bắt đầu bằng từ khóa “Open API” để khai báo tên phiên bản. Phiên bản này có vai trò định nghĩa lại toàn bộ cấu trúc trong API. Phần thông tin sẽ chứa các dữ liệu cơ bản về API như tiêu đề (title), mô tả (description) và các phiên bản (version). Cụ thể như sau:
- Title là tên mà bạn đặt cho API của mình.
- Description là thông tin chi tiết về API, có thể xuất hiện từ nhiều góc độ khác nhau. Nếu mô tả quá dài, bạn có thể ghi thành nhiều dòng và sử dụng cú pháp hỗ trợ như markdown.
- Version là phiên bản được sử dụng trong quá trình phát triển API.
Metadata hay Info có nhiệm vụ cung cấp các từ khóa liên quan đến thông tin như thông tin liên lạc, thông tin chứng chỉ và các điều khoản sử dụng,…
Servers
Để kiểm tra các API, bạn cần có một đường dẫn liên kết đến máy chủ (servers). Đây là phần tạo ra một đường dẫn cụ thể đến các máy chủ được sử dụng để thực hiện các chức năng. Trong phần này, bạn có thể tùy ý quyết định một hoặc nhiều máy chủ khác nhau.
Paths
Đây là phần quan trọng nhất của API. Nhiệm vụ của bạn và các lập trình viên khác là định nghĩa các đường dẫn (paths) xuất hiện trong API, cùng với các phương thức và tham số cụ thể liên quan.
Một số điểm cần lưu ý trong phần này bao gồm:
- Mở đầu cần bắt đầu bằng từ khóa “paths”.
- Tiếp theo là các thành phần trong API như users,…
- Sau đó là các phương thức được sử dụng trong API như Get, Post, Delete,…
- Mô tả ngắn gọn, cụ thể về API: Summary.
- Các tham số và hằng số được đưa vào API gọi là parameters. Ở phần này, bạn có thể tập hợp các tham số bắt buộc, mô tả các tham số đó hoặc thực hiện validate. Đặc biệt, bạn có thể chỉ định một model để xác định các thông số này.
- Cuối cùng là phản hồi từ server. Ở phần này, bạn có thể hoàn thiện việc định nghĩa các mã HTTP mà người dùng có thể nhận như 200, 404,… kèm theo mô tả cho từng trường hợp cụ thể.
Schema
Theo cách hiểu đơn giản, Schema được định nghĩa như một model. Schema được sử dụng trong phần khai báo thông qua từ khóa thành phần (component) và schemas.
REST APIs bao gồm một URL cơ sở mà các đường dẫn điểm cuối sẽ được nối vào. URL này được xác định bởi SCHEMA, HOST và BASEPATH.
host: petstore.swagger.io
basePath: /v2
schemes:
– https
Tất cả các API hoạt động dựa trên đường URL này, dưới đây là một ví dụ:
Tất cả các API hoạt động dựa vào đường dẫn URL- Schema là giao thức truyền tải được API sử dụng. Swagger hỗ trợ hai giao thức là http và https
schemes:
– http
– https
- Host là tên miền hoặc địa chỉ IP (IPv4) của máy chủ cung cấp API. Nó có thể bao gồm một số cổng nếu khác với cổng mặc định của lược đồ (80 cho HTTP và 443 cho HTTPS). Lưu ý rằng chỉ có thể là máy chủ lưu trữ, không bao gồm http (s): // hoặc đường dẫn phụ.
api.example.com
example.com:8089
93.184.216.34
93.184.216.34:8089
- basePath là tiền tố cho URL của tất cả các liên kết API liên quan đến máy chủ gốc. Nó cần phải bắt đầu bằng dấu gạch chéo /. Nếu không chỉ định basePath, nó sẽ mặc định là /, có nghĩa là tất cả các đường dẫn sẽ bắt đầu từ máy chủ gốc.
/v2
/api/v2
/
Paths and Operations
Là các endpoint (tài nguyên) mà API của bạn cung cấp, ví dụ như /pet, trong khi các hoạt động là các phương thức HTTP được sử dụng để thao tác với các đường dẫn đó, chẳng hạn như GET, POST hoặc DELETE.
paths:
/pet:
post:
Sau khi khai báo đường dẫn và các phương thức của API, chúng ta cần tiếp tục khai báo các đầu vào yêu cầu (request input) cho API, được gọi là Parameters (tham số).
Parameters
Trong Swagger, các tham số của hoạt động API được xác định trong phần tham số của định nghĩa hoạt động. Mỗi tham số sẽ có tên và kiểu giá trị (đối với các tham số nguyên thủy) hoặc lược đồ (đối với nội dung yêu cầu), cùng với các mô tả tùy chọn. Các dạng Parameters bao gồm:
- Query Parameters, ví dụ như: /users?role=admin.
Tham số truy vấn thường được coi là loại tham số phổ biến nhất. Chúng xuất hiện sau dấu hỏi (?) ở cuối URL yêu cầu, và các cặp tên = giá trị khác nhau được phân cách bằng dấu và (&). Tham số truy vấn có thể là bắt buộc hoặc tùy chọn.
parameters:
– in: query
name: offset
type: integer
description: Số lượng mục cần bỏ qua trước khi bắt đầu thu thập tập kết quả.
– in: query
name: limit
type: integer
description: Số lượng mục sẽ được trả về.
- Tham số đường dẫn, ví dụ: /users/{id}. Những tham số này là các phần của đường dẫn URL có thể khác nhau. Chúng thường được sử dụng để chỉ định một tài nguyên cụ thể trong một tập hợp, như một người dùng được xác định bằng ID. Một URL có thể chứa nhiều tham số đường dẫn, mỗi tham số được biểu diễn bằng dấu ngoặc nhọn {}.
paths:
/users/{id}:
get:
parameters:
– in: path
name: id # Lưu ý rằng tên giống như trong đường dẫn
required: true
type: integer
minimum: 1
description: Mã người dùng.
responses:
200:
description: Thành công
- Tham số tiêu đề, chẳng hạn như: X-MyHeader: Giá trị.
Khi thực hiện các lệnh gọi API, có thể cần gửi các tiêu đề tùy chỉnh trong yêu cầu HTTP. Swagger cho phép định nghĩa các tiêu đề yêu cầu tùy chỉnh qua tham số: header. Ví dụ: một yêu cầu GET / ping cần tiêu đề X-Request-ID:
paths:
/ping:
get:
summary: Kiểm tra xem máy chủ có hoạt động hay không.
parameters:
– in: header
name: X-Request-ID
type: chuỗi
required: true
- Tham số nội dung (body parameters) được áp dụng trong thân của các yêu cầu POST, PUT và PATCH. Các yêu cầu này có thể chứa dữ liệu như JSON hoặc XML. Trong Swagger, phần thân yêu cầu gọi là tham số nội dung. Mặc dù có thể có nhiều tham số khác (đường dẫn, truy vấn, tiêu đề), nhưng chỉ có một tham số nội dung được phép.
paths:
/users:
post:
tóm tắt: Tạo một người dùng mới.
tiêu thụ:
– application/
các tham số:
– ở: body
tên: user
miêu tả: Người dùng cần tạo.
sơ đồ:
loại: đối tượng
cần thiết:
– tênNgườiDùng
thuộc tính:
tênNgườiDùng:
loại: chuỗi
tên:
loại: chuỗi
họ:
loại: chuỗi
- Các tham số form thường được áp dụng cho những yêu cầu tải lên dữ liệu lớn như việc gửi tệp tin.
đường dẫn:
/khảo-sát:
đăng:
tóm tắt: Một khảo sát mẫu.
những định dạng hỗ trợ:
– application/x-www-form-urlencoded
các tham số:
– thuộc tính: formData
tên: name
loại: chuỗi
miêu tả: Tên của một người.
– thuộc tính: formData
tên: fav_number
loại: số
miêu tả: Số yêu thích của một người.
Phản hồi API
Swagger là một phần mềm mã nguồn mởAPI yêu cầu mọi phản hồi phải được xác định cho tất cả các hoạt động API. Mỗi thao tác cần chỉ định ít nhất một phản hồi, thường là phản hồi thành công. Phản hồi được xác định bởi mã trạng thái HTTP và dữ liệu trả về trong nội dung hoặc tiêu đề phản hồi.
đường dẫn:
/ping:
get:
chấp nhận:
– application/
các phản hồi:
200:
mô tả: OK
Trong mỗi phản hồi, định nghĩa sẽ bắt đầu bằng mã trạng thái như 200 hoặc 404. Các thao tác thường trả về mã trạng thái thành công kèm theo một hoặc nhiều mã lỗi. Mỗi trạng thái phản hồi cần có một mô tả rõ ràng.
các phản hồi:
200:
mô tả: OK
400:
mô tả: Yêu cầu không hợp lệ. ID người dùng phải là một số nguyên và lớn hơn 0.
401:
mô tả: Thông tin xác thực bị thiếu hoặc không hợp lệ.
404:
mô tả: Không tìm thấy người dùng với ID đã chỉ định.
Ngoài mã trạng thái, chúng ta cũng có thể xác định kiểu dữ liệu mà API sẽ trả về.
responses:
200:
mô tả: Đối tượng Người dùng
sơ đồ:
loại: đối tượng
các thuộc tính:
mã số:
loại: số nguyên
mô tả: Mã người dùng.
tên đăng nhập:
loại: chuỗi
mô tả: Tên người dùng.
Một tính năng thực sự hữu ích mà Swagger cung cấp là $ ref. Nó cho phép chúng ta tái sử dụng dữ liệu đã được định nghĩa, giúp tránh việc khai báo lặp lại hoặc thừa thãi.
các phản hồi:
200:
mô tả: Một đối tượng thú cưng
sơ đồ:
$ref: ‘#/definitions/Pet’
“405”:
mô tả: “Đầu vào không hợp lệ”
các định nghĩa:
Thú cưng:
kiểu: “đối tượng”
các thuộc tính:
id:
kiểu: “số nguyên”
tên:
kiểu: “chuỗi”
ví dụ: “chó con”
tình trạng:
kiểu: “chuỗi”
miêu tả: “tình trạng thú cưng trong cửa hàng”
Như đã đề cập ở trên về việc định nghĩa API trong swagger. Dưới đây là một ví dụ cụ thể:
swagger: “2.0”
thông tin:
miêu tả: “demo”
phiên bản: “1.0.0”
tiêu đề: “Cửa hàng thú cưng Swagger”
máy chủ: “petstore.swagger.io”
đường dẫn cơ sở: “/v2”
các phương thức:
– “https”
– “http”
các đường dẫn:
/thú cưng:
đăng bài:
nhãn:
– “thú cưng”
tóm tắt: “Thêm một thú cưng mới vào cửa hàng”
miêu tả: “”
operationId: “themThucung”
nhận:
– “application/”
– “application/xml”
sản xuất:
– “application/xml”
– “application/”
tham số:
– trong: “body”
tên: “body”
miêu tả: “Đối tượng Pet cần được thêm vào cửa hàng”
bắt buộc: true
hệ thống:
loại: đối tượng
các thuộc tính:
tên:
loại: chuỗi
phản hồi:
“200”:
miêu tả: “Thành công”
“405”:
miêu tả: “Dữ liệu không hợp lệ”
/thú_cưng/{id}:
lấy:
nhãn:
– “thú cưng”
tóm tắt: “Lấy Thú Cưng từ Cửa Hàng”
miêu tả: “Lấy Thú Cưng từ Cửa Hàng”
operationId: “layThuCung”
nhận dữ liệu:
– “application/”
phát sinh:
– “application/”
các tham số:
– vị trí: đường dẫn
tên: id
kiểu: số nguyên
yêu cầu: có
mô tả: ID số của người dùng cần lấy.
phản hồi:
200:
mô tả: Một đối tượng Pet
kiểu dữ liệu:
$ref: ‘#/definitions/Pet’
“405”:
mô tả: “Dữ liệu không hợp lệ”
định nghĩa:
Pet:
kiểu: “đối tượng”
thuộc tính:
id:
kiểu: “số nguyên”
tên:
kiểu: “chuỗi”
ví dụ: “chó con”
trạng thái:
kiểu: “chuỗi”
mô tả: “trạng thái của thú cưng trong cửa hàng”
Các API được Swagger hỗ trợ như thế nào?
Các tính năng hỗ trợ của SwaggerSwagger đóng vai trò rất quan trọng trong việc hỗ trợ các API. Cụ thể là:
- Công cụ Swagger giúp tối ưu hóa việc tạo giao diện tài liệu từ các file cấu hình theo tiêu chuẩn của Open API. Các nhà phát triển có thể thấy rõ ràng và cụ thể hơn khi sử dụng công cụ này.
- Mỗi API được sử dụng cung cấp cho lập trình viên thông tin chính xác và chi tiết về nguồn gốc dữ liệu. Họ cũng có thể dễ dàng nhập liệu và kiểm tra độ chính xác của kết quả để đảm bảo tính phù hợp.
- Swagger là một công cụ hữu ích để kiểm tra lại sau những thay đổi lớn trong mã nguồn. Nó hỗ trợ rất nhiều cho API trong việc mô phỏng các tình huống như điều kiện giao thông đông đúc hoặc tương tác với dữ liệu bên ngoài, tạo khả năng kiểm soát tải và kiểm tra API tự động.
Hướng dẫn cài đặt Swagger một cách đơn giản
Để cài đặt Swagger, người dùng có thể thực hiện theo 3 bước dưới đây:
– Bước 1: Tải thư viện Swagger theo hướng dẫn cụ thể sau:
- Sao chép dự án từ Github
- Sao chép thư mục dist xuất hiện trong dự án Github vừa được sao chép
- Dán (paste) vào dự án của bạn, sau đó mở file index.html trong thư mục dist để render
– Bước 2: Thiết lập cấu hình trong các API
- Ngoài việc sử dụng YAML để viết các tệp cấu hình, người dùng cũng có thể viết config theo định dạng JSON. Tuy nhiên, tốt nhất vẫn nên sử dụng YAML.
- Tạo một tệp định dạng dữ liệu trung gian (YAML) có cấu trúc tương tự như trong Swagger đã đề cập trước đó.
- Cuối cùng, lưu tệp vừa tạo vào trong các thư mục dist từ bước 1.
– Bước 3: Cập nhật các đường dẫn trong tệp cấu hình
- Đầu tiên, bạn cần mở tệp index.html trong thư mục dist,
- Tìm kiếm Swagger UI Bundle và sửa đường dẫn URL thành đường dẫn đã được tạo trước đó
- Lưu lại và khởi động máy chủ để truy cập lại vào router đã đề cập ở bước 1.
Swagger UI được sử dụng rộng rãi nhờ vào các chức năng phù hợp với các API, do đó, việc nắm vững các bước cài đặt Swagger UI là điều quan trọng mà bạn cần chú ý thực hiện.
Với Swagger, quy trình thiết kế và xây dựng tài liệu của bạn sẽ trở nên thuận tiện hơn, mang lại nhiều lợi ích cho doanh nghiệp. Hy vọng rằng, qua những thông tin mà Mytour cung cấp, bạn sẽ nắm rõ Swagger là gì? Lợi ích của Swagger là gì? Từ đó có thể sử dụng một cách hiệu quả trong công việc.
