Tìm hiểu Swagger là gì? Cách tận dụng swagger để viết API

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.

Swagger là gì? Hiểu Swagger như thế nào là đúng?

Open API là gì?

Open API có tên khá đầy đủ là Open API Specification. Đây là một loại định dạng được sử dụng để miêu tả những API cho một Rest APIs lúc bấy giờ. Chỉ với duy nhất một tệp Open API, sẽ giúp bạn diễn đạt được hàng loạt API. Phần miêu tả sẽ gồm có :

• 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 tiễn thì những thông số kỹ thuật kỹ thuật API giờ đây hoàn toàn 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à mạng lưới 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ộ miêu tả này ? Swagger được hiểu là một công cụ có mã nguồn mở và để tạo ra những đặc thù của Open API Specifications. Công cụ này sẽ giúp bạn trong sáng tạo nội dung, kiến thiết xây dựng những tài liệu cũng như việc sử dụng những Rest APIs .
Đối với những nhà tăng trưởng, khi sử dụng Swagger sẽ được tương hỗ 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 những công cụ được liệt kê ở trên thì Swagger UI được biết đến là công cụ có sự phổ cập nhất lúc bấy giờ. Với tool Swagger UI, công cụ này có hiệu quả tuyệt vời trong việc tạo giao diện cho những tài liệu bắt nguồn từ file config vận 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 diễn một cách đơn cử nhất cho những nhà tăng trưởng. Điều này sẽ giúp ích rất nhiều cho người dùng và những nhân viên lập trình trong việc điều tra và nghiên cứu và sử dụng .
Mỗi API được sử dụng trong quy trình này sẽ phân phối cho tất cả chúng ta thông tin của nguồn vào và nguồn ra một cách cụ thể nhất. Điều đặc biệt quan trọng nhất chính tất cả chúng ta hoàn toàn có thể đưa những tài liệu vào trong để kiểm tra thử những tác dụng có khả quan và đúng chuẩn hay không .

Cấu trúc cơ bản của Swagger là gì?

Việc hiểu rõ những cấu trúc cơ bản của Swagger sẽ giúp cho nhà lập trình hoàn toàn có thể hiểu rõ hơn về bộ công cụ này và vận dụng một cách linh động nhất trong từng trường hợp đơn cử .

Metadata hay Info

Đa phần mỗi Open API Specifications được dùng đều sẽ mở màn với từ khóa “ Open API ” nhằm mục đích mục tiêu cho việc khai báo tên của phiên bản. Phiên bản được vận dụng sẽ có ý nghĩa trong việc định nghĩa lại hàng loạt những cấu trúc ở trong API. Phần info sẽ chứa những thông tin cơ bản về API như tiêu đề ( title ), miêu tả ( description ) và những 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 tính năng trong việc giúp đưa ra những từ khóa về những thông tin tương quan như thông tin liên lạc, thông tin về chứng từ và những lao lý trong việc sử dụng, …

Servers

Để hoàn toàn có thể kiểm tra được những API thì bạn phải có một đường dẫn link tương quan đến sever ( servers ). Và đây là phần tạo nên một đường dẫn đơn cử đến servers được sử dụng để thực thi công dụng trên. Trong phần này, trọn vẹn tùy thuộc vào quyết định hành động của bạn để xác đinh một hay nhiều sever 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, việc làm của bạn và người lập trình khác chính là định nghĩa những đường dẫn ( paths ) Open trong API hay những phương pháp đơn cử và những tham số đơn cử sống sót trong phần này .
Một số chú ý quan tâm 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 thuần nhất thì Schema được định nghĩa như một Mã Sản Phẩm. Schema được sử dụng trong phần khai báo trải 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à những đường dẫn điểm cuối được nối vào. URL này được xác lập bởi SCHEMA, HOST và BASEPATH .
host : petstore.swagger.io
basePath : / v2
schemes :
– https
Tất cả API đều hoạt động giải trí nhờ vào đường URL này, dưới đây là ví dụ :

• Schemalà giao thức truyền tải được sử dụng bởi API. Swagger tương hỗ 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ủ tàng trữ phân phối API.Nó hoàn toàn có thể chứa 1 số ít 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ỉ hoàn toàn có thể là máy chủ tàng 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

• basePathlà tiền tố của URL cho tổng thể những đường link API màliên quan đến gốc sever. Nó phải khởi đầ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à toàn bộ những đường dẫn đều khởi đầu từ sever gốc .

/ v2
/ api / v2
/

Paths and Operations 

Là những điểm cuối ( tài nguyên ) được API của bạn hiển thị, ví dụ điển hình như / pet và hoạt động giải trí là những phương pháp HTTP được sử dụng để thao tác những đường dẫn đó, ví dụ điển hình như GET, POST hoặc DELETE .
paths :
/ pet :
post :
Khi tất cả chúng ta đã khai báo đường dẫn đến API và những phương pháp của API, tất cả chúng ta cần chuyển sang khai báo những nguồn vào nhu yếu ( request input ) API, được gọi là Parameters ( tham số ) .

Parameters 

Trong Swagger, những tham số hoạt động giải trí API được xác lập trong phần tham số của định nghĩa hoạt động giải trí. 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 đồ ( so với nội dung nhu yếu ) và những diễn đạt tùy chọn. Các dạng Parameters như thể :

• Query Parameters, ví dụ điển hình như : / users ? role = admin .

Tham số truy vấn hoàn toàn có thể được nhận xét là loại tham số thông dụng nhất. Chúng Open sau dấu chấm hỏi ( ? ) Ở cuối URL nhu yếu và những cặp tên = giá trị khác nhau được phân tách bằng dấu và ( và ). Tham số truy vấn hoàn toàn có thể được nhu yế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, ví dụ điển hình như : / users / { id }. Tham số đường dẫn gồm những thành phần của đường dẫn URL hoàn toàn có thể khác nhau. Chúng thường được sử dụng để trỏ đến một tài nguyên đơn cử trong một bộ sưu tập, ví dụ điển hình như một người dùng được xác lập bằng ID. Một URL hoàn toàn có thể có nhiều tham số đường dẫn, mỗi tham số được bộc lộ 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 hoàn toàn có thể nhu yếu gửi những tiêu đề tùy chỉnh cùng với nhu yếu HTTP. Swagger được cho phép bạn xác lập những tiêu đề nhu yếu tùy chỉnh trong tham số : header. Ví dụ : một lệnh gọi tới GET / ping nhu yế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 toàn thân of POST, PUT and PATCH requests .Các nhu yếu POST, PUT và PATCH hoàn toàn có thể có nội dung nhu yếu ( tải trọng ) như tài 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ỉ hoàn toàn có thể có một tham số nội dung, mặc dầu những hoạt động giải trí hoàn toàn có thể có những 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 toàn thân
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ì được sử dụng cho những nhu yếu truyền lên nhiều data ví dụ điển hình 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 nhu yếu những phản hồi phải được chỉ định cho toàn bộ những hoạt động giải trí API. Mọi thao tác phải xác lập tối thiểu một phản hồi, thường là một phản hồi thành công xuất sắc. Phản hồi được xác lập bằng mã trạng thái HTTP của nó và tài 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ả.

Xem thêm: Ép kiểu dữ liệu trong lập trình C/C++

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, tất cả chúng ta cũng hoàn toàn có thể khai báo kiểu tài 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 tương hỗ là USD ref. Nó giúp chúng tôi sử dụng lại tài liệu mà đã xác lập. 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 :
USD 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ư đã khám phá ở trên về swagger định nghĩa API. Dưới đây là một ví dụ đơn cử :
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 toàn thân ”
name : “ body toàn thân ”
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 :
USD 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 tương hỗ 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

Để setup Swagger, người dùng hoàn toàn 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 thông dụng cũng như vận dụng thoáng rộng của Swagger UI trải qua những công dụng tương thích và thích hợp với những API, do đó việc hiểu rõ những bước setup Swagger UI là điều quan trọng mà bạn thiết yếu phải triển khai .

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:

Source: https://final-blade.com
Category : Kiến thức Internet