Swagger nghĩa là gì

Swag là gì?

Swag là cụm từ để chỉ những người có khiếu thẩm mỹ tốt cùng khả năng kết hơp gu thời trang chất chơi, phong phú, hợp mốt và bắt trend với thời đại. Điều đó đồng nghĩa với việc nếu bạn muốn trở thành một swagger chuẩn tiêu chí thì cần có sự tinh tế cho việc mix đồ thời trang sao cho phù hợp đặc biệt là phải hợp mốt bao gồm giày dép, túi xách và các trang phục cần có sự hài hòa. Không thể phủ nhận cụm từ Swag đã trở thành xu hướng sau khi du nhập sang làn sóng châu Á với bộ phim cô nàng cử tạ trong đó nữ chính là Kim Bok Joo.

Tuy nhiên hiện nay có một số bộ phận bạn trẻ đang hiểu sai lệch về ý nghĩa từ swag nghĩa là gì và có những hành vi sai lệch hay cách thể hiện và sử dụng cụm từ này trong đời sống hàng ngày gây phản cảm. Bản chất của cụm từ Swag có nghĩa là sành điệu, ăn chơi tuy nhiên không đồng nghĩa với việc đua đòi và lạm dụng trong việc chạy theo xu hướng.

Sử dụng cụm từ Swag khi nào?

Như các bạn đã biết thì cụm từ Swag với ý nghĩa chính thuộc về thời trang là phong cách cá nhân của mỗi người thể hiện cá tính riêng cũng như style và khiếu thẩm mỹ của mỗi cá nhân, ngoài việc sử dụng trong ngữ cảnh nói về phong cách thời trang thì cụm từ này còn được sử dụng trên các mạng xã hội, trang cá nhân hoặc giao tiếp hàng ngày, trong các bài hát rap…

Tùy thuộc vào mỗi trưởng hợp, ngữ cảnh khác nhau mà từ Swag còn được hiểu với nhiều ý nghĩa khác nhau, từ swag khi du nhập sang các nước cũng được biến thể với nhiều ngữ nghĩa và các bạn nên lưu ý trong viêc phân biệt khái niệm cụm từ swag là gì để tránh gây sai lệch khi sử dụng hàng ngày.

Tổng hợp các nghĩa của từ Swag

Muốn biết cách sử dụng hợp ý thì nhất định các bạn không được bỏ qua những ngữ nghĩa của chúng, cụm từ Swag có thể được sử dụng trong việc học tập theo xu hướng thời trang của thần tượng trong những bộ phim Hàn, Swag với nghĩa chính là thể hiện sự phong cách và swag theo xu hướng unisex là có thể thích hợp sử dụng cho cả nam và nữ, từ đó mới có các cụm từ như swag boy hay swag girl.

Cụm từ Swag cũng được các bạn trẻ xem là tiêu chuẩn cho việc kết hợp đồ thời trang, phong cách và hợp xu hướng tính tới thời điểm hiện tại

1. Bạn hiểu như thế nào về Swagger là gì?

Hiểu ý nghĩa của Swagger là gì để giúp bạn có thể ứng dụng công cụ này một cách tốt nhất cho công việc của mình.

Swagger

Tuy nhiên, trước khi đi tìm hiểu định nghĩa của Swagger thì bạn cần biết Open API là gì và có mối tác động, liên hệ ra sao với Swagger.

1.1. Hiểu gì về Open API?

Open API được biết đến với tên đầy đủ là Open API Specification. Đây được biết đến là một loại định dạng dùng để mô tả API cho một Rest APIs hiện nay. Với duy nhất một file Open API, bạn sẽ có thể mô tả được toàn bộ API. Điều này có nghĩa là việc mô tả sẽ bao gồm cả những nội dung sau đây:

- Tạo điều kiện hoạt động các các endpoints hay là các users cũng như cách thức hoạt động của các endpoints đó như get/users, post/users.

- Hiển thị rõ được các tham số về đầu vào và đầu ra của mỗi hoạt động.

- Thể hiện các phương thức xác thực được sử dụng.

Open API là gì?

- Thể hiện các thông tin liên lạc, các chứng chỉ, những điều khoản liên quan đến việc sử dụng và các thông tin liên quan khác.

Thực tế thì API Specifications hiện có thể được viết bằng các định dạng như JSOL hay YAML. Đây được biết đến là hai định dạng có lợi cho cả người dùng và hệ thống máy tính khi rất dễ đọc, dễ hiểu để sử dụng.

1.2. Định nghĩa Swagger là gì?

Nếu như Open API có ý nghĩa quan trọng như trên thì điều gì đã tạo nên được bộ mô tả này? Và đó chính là Swagger. Swagger được hiểu là một công cụ có mã nguồn mở và dùng để xây dựng nên Open API Specifications. Công cụ này sẽ giúp bạn trong việc thiết kế, tạo dựng các tài liệu cũng như việc sử dụng Rest APIs.

Với các nhà phát triển, khi sử dụng Swagger sẽ được cung cấp 3 tool chính như sau:

Swagger là gì?

- Tool Swagger Editor: Được sử dụng để thiết kế, xây dựng nên các APIs một cách mới hoàn toàn hoặc là có thể edit lại từ những APIs có sẵn với việc tận dụng một file config.

- Tool Swagger Codegen: Có tác dụng trong việc generate ra code thông qua sử dụng các file config sẵn có trước đó.

- Tool Swagger UI: Ứng dụng trong việc generate các file ra HTML, CSS,...xuất phát từ một file config.

Để có thể thực hiện việc viết document cho Swagger thì các developers sẽ có 2 cách để tiếp cận với bộ mã nguồn mở này.

- Cách 1: Top down approach: dùng để thiết kế nên các APIs trước khi thực hiện việc code liên quan.

- Cách 2: Bottom down approach: dùng để mô tả các vấn đề, thông số liên quan API thông qua việc sử dụng thiết kế có sẵn của file config.

Các tool được sử dụng

Với những tool được liệt kê ở trên của Swagger thì Swagger UI được biết đến là một tool có sự thông dụng phổ biến nhất hiện nay. Với tool Swagger UI, tool này có ứng dụng rất lớn trong việc xây dựng giao diện cho các tài liệu bắt nguồn từ file config áp dụng dưới chuẩn của Ipen API. Giao diện được tạo ra bởi tool này thường có tính tường minh và khá rõ ràng, hiện ra 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 lớn cho cả người dùng lẫn các lập trình viên trong việc đọc hiểu và sử dụng. Thêm vào đó, đây cũng là dẫn chứng có việc các developers sử dụng file config nhưng lại có sự tách biệt một cách hoàn toàn giữa các tác vụ với nhau.

Mỗi API được sử dụng trong quá trình này sẽ cho chúng ta biết một cách chính xác nhất về nguồn vào và nguồn ra một cách chi tiết. Thêm vào đó chính là việc những trường cần phải được gửi lên hệ thống cũng như các trạng thái kết quả có thể được trả về. Điều đặc biệt nhất có lẽ chính là việc ta có thể đưa các dữ liệu vào trong để test thử các kết quả liệu có thực sự chính xác và đảm bảo tính đúng đắn hay không.

Cơ bản về Swagger

• Báo cáo
• Thêm vào series của tôi

Như chúng ta biết hiện nay việc phát triển các ứng dụng hay hệ thống đều cần sử dụng đến một thứ không thể thiếu là API. Nó là các phương thức, giao thức kết nối với các thư viện và ứng dụng khác. Nó là viết tắt của Application Programming Interface – giao diện lập trình ứng dụng. API cung cấp khả năng cung cấp khả năng truy xuất đến một tập các hàm hay dùng. Và từ đó có thể trao đổi dữ liệu giữa các ứng dụng.

Vậy nên chúng ta luôn cần một Tài liệu hướng dẫn API. Nó là một nội dung kỹ thuật, nó chứa tất cả các thông tin được yêu cầu để có thể làm việc với API, với thông tin chi tiết về các tài nguyên, phương thức, các request và response, thông tin chứng thực, … được hỗ trợ bởi các hướng dẫn và ví dụ. Một công cụ rất phổ biến hiện nay để giúp làm một Tài liệu hướng dẫn API đó là Swagger.

Swagger là gì

Swagger là một bộ công cụ mã nguồn mở để xây dựng OpenAPI specifications giúp chúng ta có thể thiết kế, xây dựng tài liệu và sử dụng REST APIs.
Swagger cung cấp 3 tools chính cho các developers :

• Swagger-Editor : dùng để design lên các APIs hoàn toàn mới hoặc edit lại các APIs có sẵn thông qua 1 file config.
• Swagger-Codegen : dùng để generate ra code từ các file config có sẵn
• Swagger-UI : dùng để generate ra file html,css,… từ 1 file config.

Trong các tools trên, Swagger UI được sử dụng nhiều nhất, nó giúp sinh ra giao diện cho tài liệu từ file config dưới chuẩn OpenAPI. Giao diện được hiện ra rõ ràng và tường minh. Dễ dàng đọc hiểu cho cả lập trình viên lẫn người dùng. Sử dụng file config nhưng hoàn toàn tách biệt tác vụ với nhau. Trong bài này mình sẽ giới thiệu Swagger phiên bản 2.0 .

Cấu trúc cơ bản của file Swagger

Đầu tiên 1 file swagger có thể viết bằng JSON hoặc YAML.

• Metadata: Mọi thông số kỹ thuật của Swagger đều bắt đầu với phiên bản Swagger . Phiên bản Swagger xác định cấu trúc tổng thể của đặc tả API - những gì bạn có thể ghi lại và cách bạn ghi lại nó. Ngoài ra các thông tin chi tiết như tiêu đề, mô tả hay version của bản api hiện tại cũng được khai báo tại đây.
• Base Url: Nơi bạn sẽ định nghĩa host của server, đường dẫn cơ bản cũng như giao thức https hoặc http.
• Consumes, Produces: xác định các loại MiME được API hỗ trợ
• Paths: xác định các điểm cuối riêng lẻ [đường dẫn] trong API của bạn và các phương thức HTTP [hoạt động] được hỗ trợ bởi các điểm cuối này. Và đây là phần quan trọng chứa thông tin API của bạn sẽ như thế nào bằng đường dẫn API, phương thức [GET, POST, PUT...], request [query, path, body..], response API

API Host and Base URL

REST APIs có một URL cơ sở mà các đường dẫn điểm cuối được nối vào. Đường url này được định nghĩa bởi schema, host, basePath

host: petstore.swagger.io basePath: /v2 schemes: - https

Tất cả API đều được dựa trên đường URL này ví dụ:

• Schema là giao thức truyền được API sử dụng. Swagger hỗ trợ 2 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ủ lưu trữ cung cấp API. Nó có thể bao gồm 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 đây chỉ phải là máy chủ lưu trữ, không có 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ố URL cho tất cả các đường dẫn API, liên quan đến gốc máy chủ. Nó phải bắt đầu bằng một dấu gạch chéo /. Nếu basePath không được chỉ định, nó sẽ mặc định là /, nghĩa 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] mà 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 này, chẳng hạn như GET, POST hoặc DELETE.

paths: /pet: post:

Khi đã khai báo đường dẫn đến API và phương thức của API, chúng ta cần tiếp tục khai báo đến request input của API gọi là Parameters

Parameters

Trong Swagger, các tham số hoạt động API được xác định trong phần tham số trong định nghĩa hoạt động. Mỗi tham số có tên, kiểu giá trị [đối với tham số giá trị nguyên thủy] hoặc lược đồ [đối với nội dung yêu cầu] và mô tả tùy chọn. Các dạng Parameters như là :

• query parameters, ví dụ /users?role=admin. Tham số truy vấn là loại tham số phổ biến nhất. Chúng xuất hiện ở cuối URL yêu cầu sau dấu chấm hỏi [?], Với 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 và 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ụ /users/{id}. Tham số đường dẫn là 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ư người dùng được xác định bằng ID. Một URL có thể có một số 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ụ X-MyHeader: Value. Một 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 một yêu cầu HTTP. Swagger cho phép bạn xác định tiêu đề yêu cầu tùy chỉnh như trong: tham số tiêu đề. Ví dụ: giả sử, một cuộc 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 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ó phần thân yêu cầu [tải trọng], chẳng hạn như dữ liệu JSON hoặc XML. Theo thuật ngữ Swagger, nội dung 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ù 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 sử dụng cho những request truyền lên nhiều data ví dụ như việc upload file chả hạn

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

Một API cần chỉ định các phản hồi cho tất cả các hoạt động API. Mỗi thao tác phải có ít nhất một phản hồi được xác định, 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ả về trong nội dung phản hồi và / hoặc tiêu đề

paths: /ping: get: produces: - application/json responses: 200: description: OK

Trong câu trả lời, mỗi định nghĩa phản hồi bắt đầu bằng một mã trạng thái, chẳng hạn như 200 hoặc 404. Một hoạt động thường trả về một 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 những trạng thái status ra, chúng ta có thể khai báo những dạng 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ứ rất hay của Swagger hỗ trợ là $ref. Nó giúp chúng ta có thể sử dụng lại những data mà ta đã định nghĩa. Nó giúp tránh việc trùng lặp hay khai báo nhiều lần.

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ư trên chúng ta đã tìm hiểu cơ bản để viết được một file swagger định nghĩa API. Sau đây là một ví dụ mình đã viết ra:

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"

Hy vọng bài viết của mình sẽ giúp các bạn hiểu và sử dụng Swagger một cách tốt. Bài viết được tham khảo từ : //swagger.io/docs