Swagger là gì? Đối với những người đam mê công nghệ Swagger có lẽ đã trở thành một thuật ngữ khá quen thuộc. Tuy nhiên, đối với những người ngoài ngành sẽ rất dễ nhầm tưởng Swagger giống như một khẩu hiệu mà giới trẻ ngày nay thường sử dụng. Vậy, ý nghĩa của Swagger là gì? Chức năng của Swagger là gì? Hãy cùng Muaban.net theo dõi bài viết dưới đây để hiểu rõ hơn về Swagger.
Tóm Tắt
Swagger là gì? Hiểu Swagger như thế nào là đúng?
Open API là gì?
Open API có tên đầy đủ là Open API Specification. Đây là một loại định dạng được sử dụng để mô tả các API cho một Rest APIs hiện nay. Chỉ với duy nhất một tệp Open API, sẽ giúp bạn mô tả được toàn bộ API. Phần mô tả sẽ bao gồm:
- Tạo điều kiện thuận lợi cho thiết bị đầu cuối hoặc người dùng và hoạt động của họ.
- Hiển thị chi tiết các thông số về đầ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 được sử dụng.
- Hiện thị các thông tin liên hệ chứng chỉ và các điều khoản liên quan khác.
Trên thực tế thì các thông số kỹ thuật API giờ đây có thể được viết bằng định dạng như JSOL hay YAML. Đây là hai kiểu định dạng có lợi cho cả người dùng và hệ thống máy tính khi chúng dễ đọc hiểu và sử dụng.
>>> Tham khảo thêm: IT là gì? Những điều cần biết về công việc của ngành IT
Khái niệm Swagger là gì?
Với tầm quan trọng của Open API như vậy, thì yếu tố nào đã tạo nên bộ mô tả này? Swagger được hiểu là một công cụ có mã nguồn mở và để tạo ra các đặc điểm của Open API Specifications. Công cụ này sẽ giúp bạn trong sáng tạo nội dung, xây dựng các tài liệu cũng như việc sử dụng các Rest APIs.
Đối với các nhà phát triển, khi sử dụng Swagger sẽ được hỗ trợ 3 tool chính như sau:
- Tool Swagger Editor: Được sử dụng để thiết kế và xây dựng các APIs theo cách hoàn toàn mới hoặc sửa đổi các APIs hiện có với việc tận dụng một file config.
- Tool Swagger Codegen: Hiệu quả để tạo ra các mã (code) bằng cách sử dụng các file conid có sẵn trước đó.
- Tool Swagger UI: Ứng dụng cho phép tạo các file ra HTML, CSS,…bắt đầu từ một file config.
Với các công cụ được liệt kê ở trên thì Swagger UI được biết đến là công cụ có sự phổ biến nhất hiện nay. Với tool Swagger UI, công cụ này có công dụng tuyệt vời trong việc tạo giao diện cho các tài liệu bắt nguồn từ file config áp dụng theo tiêu chuẩn của Ipen API. Giao diện được tạo ra bởi công cụ này thường 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 sẽ giúp ích rất nhiều cho người dùng và các chuyên viên lập trình trong việc nghiên cứu và sử dụng.
Mỗi API được sử dụng trong quá trình này sẽ cung cấp cho chúng ta thông tin của nguồn vào và nguồn ra một cách chi tiết nhất. Điều đặc biệt nhất chính chúng ta có thể đưa các dữ liệu vào trong để kiểm tra thử 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ì?
Việc hiểu rõ các cấu trúc cơ bản của Swagger sẽ giúp cho nhà lập trình có thể hiểu rõ hơn về bộ công cụ này và áp dụng một cách linh hoạt nhất trong từng tình huống cụ thể.
Metadata hay Info
Đa phần mỗi Open API Specifications được dùng đều sẽ bắt đầu với từ khóa “Open API” nhằm mục đích cho việc khai báo tên của phiên bản. Phiên bản được áp dụng sẽ có ý nghĩa trong việc định nghĩa lại toàn bộ những cấu trúc ở trong API. Phần info sẽ chứa các thông tin cơ bản về API như tiêu đề (title), mô tả (description) và các phiên bản (version). Cụ thể thì:
- Title chính là tên mà chúng ta đặt cho API của mình.
- Description chính là thông tin chi tiết về API và xuất hiện ở nhiều khía cạnh khác nhau. Việc mô tả này, bạn hoàn toàn có thể ghi thành nhiều dòng nếu như quá dài 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 xây dựng với API.
Metadata hay Info đảm nhiệm chức năng trong việc giúp đưa ra các từ khóa về các thông tin liên quan như thông tin liên lạc, thông tin về chứng chỉ và các điều khoản trong việc sử dụng,…
Servers
Để có thể kiểm tra được các API thì bạn phải có một đường dẫn liên kết liên quan đến máy chủ (servers). Và đây là phần tạo nên một đường dẫn cụ thể đến servers được sử dụng để thực hiện chức năng trên. Trong phần này, hoàn toàn tùy thuộc vào quyết định của bạn để xác đinh một hay nhiều máy chủ khác nhau.
Paths
Là phần chủ chốt, trọng tâm của API được sử dụng. Với phần này, công việc của bạn và người lập trình khác chính là định nghĩa các đường dẫn (paths) xuất hiện trong API hay các phương thức cụ thể và các tham số cụ thể tồn tại trong phần này.
Một số lưu ý trong phần này gồm:
- Mở đầu phải bằng từ khóa “paths”.
- Sau đó mới đến các thành phần có trong API như users,..
- Tiếp đó là các phương thức được sử dụng trong API như Get, Post, Delete,…
- Mô tả một cách ngắn gọn, cụ thể của API: Summary
- Những tham số, hằng số được đưa vào trong API gọi là parameters. Với phần này bạn có thể thực hiện việc tập hợp các tham số bắt buộc, thực hiện việc mô tả những tham số đó hoặc là validate. Ngoài ra, phần đặc biệt ở phần này là bạn có thể chỉ định một model bất kỳ nhằm mục đích xác định cho các thông số này.
- Phần cuối cùng là trả về của server đó. Với phần trả về này thì bạn có thể hoàn chỉnh việc định nghĩa cho các HTTP code mà người dùng có thể nhận được như 200, 404,… kèm theo là các dòng mô tả xuất hiện với cho từng trường hợp cụ thể.
Schema
Theo cách hiểu đơn giản nhất thì Schema được định nghĩa như một model. Schema được sử dụng trong phần khai báo thông qua việc sử dụng từ khóa thành phần (component) và schemas.
>>> Tham khảo thêm: Lập trình viên và những điều có thể bạn chưa biết!
REST APIs gồm 1 URL cơ sở mà các đường dẫn điểm cuối đượ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ả API đều hoạt động nhờ vào đường URL này, dưới đây là ví dụ:
- Schema
là giao thức truyền tải được sử dụng bởi API. Swagger hỗ trợ 2 giao thức gồm http và https
schemes:
– http
– https
- Host
còn được gọi là tên miền hoặc địa chỉ IP (IPv4) của máy chủ lưu trữ cung cấp API.
Nó có thể chứa một số cổng nếu nó khác với cổng mặc định cho lược đồ (80 cho HTTP và 443 cho HTTPS). Lưu ý rằng đây chỉ có thể là máy chủ lưu trữ, không phải 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ố của URL cho tất cả các đường link API màliên quan đến gốc máy chủ. Nó phải bắt đầu bằng dấu gạch chéo /. Nếu basePath không được chỉ định, nó sẽ mặc định thành /, tức là tất cả các đường dẫn đều bắt đầu từ máy chủ gốc.
/v2
/api/v2
/
Paths and Operations
Là các điểm cuối (tài nguyên) được API của bạn hiển thị, chẳng hạn như / pet và hoạt động là các phương thức HTTP được sử dụng để thao tác các đường dẫn đó, chẳng hạn như GET, POST hoặc DELETE.
paths:
/pet:
post:
Khi chúng ta đã khai báo đường dẫn đến API và các phương thức của API, chúng ta cần chuyển sang khai báo các đầu vào yêu cầu (request input) API, được gọi là Parameters (tham số).
Parameters
Trong Swagger, các tham số 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ố có tên và kiểu giá trị (xét với tham số giá trị nguyên thủy) hay lược đồ (đối với nội dung yêu cầu) và các mô tả tùy chọn. Các dạng Parameters như là :
-
Query Parameters,chẳng hạn như: /users?role=admin.
Tham số truy vấn có thể được nhận xét là loại tham số phổ biến nhất. Chúng xuất hiện sau dấu chấm hỏi (?) Ở cuối URL yêu cầu và các cặp tên = giá trị khác nhau được phân tách bằng dấu và (&). Tham số truy vấn có thể được yêu cầu hoặc tùy chọn.
parameters:
– in: query
name: offset
type: integer
description: The number of items to skip before starting to collect the result set.
– in: query
name: limit
type: integer
description: The numbers of items to return.
-
Path Parameters, chẳng hạn như: /users/{id}. Tham số đường dẫn gồm các thành phần của đường dẫn URL có thể khác nhau.
Chúng thường được sử dụng để trỏ đến một tài nguyên cụ thể trong một bộ sưu tập, chẳng hạn như một người dùng được xác định bằng ID. Một URL có thể có nhiều tham số đường dẫn, mỗi tham số được biểu thị bằng dấu ngoặc nhọn {}.
paths:
/users/{id}:
get:
parameters:
– in: path
name: id # Note the name is the same as in the path
required: true
type: integer
minimum: 1
description: The user ID.
responses:
200:
description: OK
-
Header parameters, ví dụ như: X-MyHeader: Value.
Các lệnh gọi API có thể yêu cầu gửi các tiêu đề tùy chỉnh cùng với yêu cầu HTTP. Swagger cho phép bạn xác định các tiêu đề yêu cầu tùy chỉnh trong tham số: header. Ví dụ: một lệnh gọi tới GET / ping yêu cầu tiêu đề X-Request-ID:
paths:
/ping:
get:
summary: Checks if the server is alive.
parameters:
– in: header
name: X-Request-ID
type: string
required: true
-
Body parameters (tham chiếu nội dung) được sử dụng trong the body of POST, PUT and PATCH requests.
Các yêu cầu POST, PUT và PATCH có thể có nội dung yêu cầu (tải trọng) như dữ liệu JSON hoặc XML. Trong thuật ngữ Swagger, phần thân yêu cầu được gọi là tham số nội dung. Chỉ có thể có một tham số nội dung, mặc dù các hoạt động có thể có các tham số khác (đường dẫn, truy vấn, tiêu đề).
paths:
/users:
post:
summary: Creates a new user.
consumes:
– application/json
parameters:
– in: body
name: user
description: The user to create.
schema:
type: object
required:
– userName
properties:
userName:
type: string
firstName:
type: string
lastName:
type: string
-
Form parameters thông thường được sử dụng cho những yêu cầu truyền lên nhiều data chẳng hạn như việc upload file
paths:
/survey:
post:
summary: A sample survey.
consumes:
– application/x-www-form-urlencoded
parameters:
– in: formData
name: name
type: string
description: A person’s name.
– in: formData
name: fav_number
type: number
description: A person’s favorite number.
Response API
API yêu cầu các phản hồi phải được chỉ định cho tất cả các hoạt động API. Mọi thao tác phải xác định ít nhất một phản hồi, thường là một phản hồi thành công. Phản hồi được xác định bằng mã trạng thái HTTP của nó và dữ liệu được trả lại trong nội dung phản hồi và / hoặc tiêu đề.
paths:
/ping:
get:
produces:
– application/json
responses:
200:
description: OK
Trong phản hồi, mỗi định nghĩa phản hồi bắt đầu bằng mã trạng thái, chẳng hạn như 200 hoặc 404. Các thao tác thường trả về mã trạng thái thành công và một hoặc nhiều trạng thái lỗi. Mỗi trạng thái phản hồi yêu cầu một mô tả.
responses:
200:
description: OK
400:
description: Bad request. User ID must be an integer and bigger than 0.
401:
description: Authorization information is missing or invalid.
404:
description: A user with the specified ID was not found.
Ngoài trạng thái trạng thái, chúng ta cũng có thể khai báo kiểu dữ liệu mà API sẽ trả về.
responses:
200:
description: A User object
schema:
type: object
properties:
id:
type: integer
description: The user ID.
username:
type: string
description: The user name.
Một thứ thực sự tuyệt vời mà Swagger hỗ trợ là $ ref. Nó giúp chúng tôi sử dụng lại dữ liệu mà đã xác định. Nó giúp tránh việc khai báo trùng lặp hoặc nhiều.
responses:
200:
description: A Pet object
schema:
$ref: ‘#/definitions/Pet’
“405”:
description: “Invalid input”
definitions:
Pet:
type: “object”
properties:
id:
type: “integer”
name:
type: “string”
example: “doggie”
status:
type: “string”
description: “pet status in the store”
Như đã tìm hiểu ở trên về swagger định nghĩa API. Dưới đây là một ví dụ cụ thể:
swagger: “2.0”
info:
description: “demo”
version: “1.0.0”
title: “Swagger Petstore”
host: “petstore.swagger.io”
basePath: “/v2”
schemes:
– “https”
– “http”
paths:
/pet:
post:
tags:
– “pet”
summary: “Add a new pet to the store”
description: “”
operationId: “addPet”
consumes:
– “application/json”
– “application/xml”
produces:
– “application/xml”
– “application/json”
parameters:
– in: “body”
name: “body”
description: “Pet object that needs to be added to the store”
required: true
schema:
type: object
properties:
name:
type: string
responses:
“200”:
description: “Success”
“405”:
description: “Invalid input”
/pets/{id}:
get:
tags:
– “pet”
summary: “Get Pet of Store”
description: “Get Pet of Store”
operationId: “getPets”
consumes:
– “application/json”
produces:
– “application/json”
parameters:
– in: path
name: id
type: integer
required: true
description: Numeric ID of the user to get.
responses:
200:
description: A Pet object
schema:
$ref: ‘#/definitions/Pet’
“405”:
description: “Invalid input”
definitions:
Pet:
type: “object”
properties:
id:
type: “integer”
name:
type: “string”
example: “doggie”
status:
type: “string”
description: “pet status in the store
API được Swagger hỗ trợ như thế nào?
Swagger đóng một vai trò quan trọng rất lớn trong việc hỗ trợ API. Cụ thể là:
- Công cụ Swagger có chức năng tối ưu trong việc xây dựng giao diện cho các tài liệu có nguồn từ các file config áp dụng dưới chuẩn của Ipen API. Các nhà phát triển có thấy rõ được sự rõ ràng và cụ thể khi sử dụng công cụ này.
- Mỗi API được sử dụng sẽ cho các nhà lập trình viên biết thông tin chính xác nhất và chi tiết nhất về nguồn gốc của dữ liệu. Ngoài ra, lập trình viên cũng có thể dễ dàng nhập và kiểm tra độ chính xác của kết quả và đảm bảo chúng là 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 về code (mã). Công cụ này trợ giúp 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 cao điểm hoặc tương tác với dữ liệu có nguồn nước ngoài, tạo kiểm soát tải và kiểm tra API tự động.
Hướng dẫn cài đặt Swagger đơn giản
Để cài đặt Swagger, người dùng có thể làm theo 3 bước dưới đây:
– Bước 1: Tải thư viện của Swagger bằng cách chỉ dẫn cụ thể sau:
- Clone dự án Github
- Copy thư mục dist xuất hiện trong dự án Github vừa được clone về
- Dán (paste) vào dự án, tiếp đó lựa chọn render file index.html có trong dist
– Bước 2: Thiết lập config ở trong các cấu hình APIs
- Bên cạnh cách 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 dưới dạng Jsol. Tuy vậy, tốt nhất nên viết ở định dạng yaml
- Tạo một file định dạng dữ liệu trung gian (yaml) với cấu trúc giống như trong Swagger đã có ở trước đó.
- Sau cùng chỉ cần lưu lại tệp vừa tạo vào trong các thư mục dist ở bước 1.
– Bước 3: Tiến hành cập nhật các đường dẫn trong file config
- Đầu tiên bạn cần mở tệp Index.html có trong dist,
- Tìm kiếm Swagger UI Bundle và tiến hành việc sửa đường dẫn url thành đường dẫn đã được tạo trước đó
- Lưu lại rồi chạy máy chủ và truy cập lại vào router đã được nói đến ở bước 1.
Được sử dụng phổ biến cũng như áp dụng rộng rãi của Swagger UI thông qua các chức năng phù hợp và thích hợp với các API, vì thế việc hiểu rõ các bước cài đặt Swagger UI là điều quan trọng mà bạn cần thiết phải thực hiện.
Với Swagger, việc thiết kế và xây dựng các tài liệu của bạn sẽ trở nên dễ dàng hơn, mang lại nhiều lợi ích hơn cho doanh nghiệp. Hy vọng rằng, với những thông tin mà Muaban.net mang lại, bạn sẽ hiểu rõ Swagger là gì? Lợi ích của Swagger là gì? Từ đó sử dụng một cách hiệu quả nhất trong công việc.
>>> Tham khảo thêm:
