Swagger là gì

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

Bạn đang xem: Swagger là gì

Vậy nên họ luôn cần một Tài liệu khuyên bảo API. Nó là 1 trong 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 bài toán với API, cùng với thông tin cụ thể về các tài nguyên, phương thức, các request cùng response, thông tin chứng thực, … được cung cấp bởi các hướng dẫn với ví dụ.Một phép tắc rất phổ biến bây chừ để giúp làm cho một Tài liệu giải đáp API đó là Swagger.

Swagger là gì

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

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

Trong các tools trên, Swagger UI được sử dụng nhiều nhất, nó góp sinh ra đồ họa cho tư liệu từ tệp tin config dưới chuẩn chỉnh OpenAPI. Hình ảnh được hiện tại ra ví dụ và tường minh. Thuận tiện đọc hiểu cho tất cả lập trình viên lẫn người dùng. Sử dụng file config tuy thế hoàn toàn tách bóc biệt tác vụ với nhau. Trong bài này mình sẽ ra mắt Swagger phiên phiên bản 2.0 .

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

Đầu tiên 1 file swagger hoàn toàn có thể viết bởi JSON hoặc YAML.

Metadata: Mọi thông số kỹ thuật của Swagger đều ban đầu với phiên phiên bản Swagger . Phiên bản Swagger xác định kết cấu tổng thể của sệt tả API - phần lớn gì chúng ta có thể ghi lại và phương pháp bạn đánh dấu nó. Hình như các thông tin cụ thể như tiêu đề, trình bày hay version của bạn dạng api hiện nay tại cũng khá được khai báo trên đây.

Xem thêm: Danh Hiệu Mdrt Là Gì ? Quyền Lợi Và Yêu Cầu Dành Cho Các Thành Viên Mdrt

Base Url: Nơi bạn sẽ định nghĩa host của server, băng thông cơ bạn dạng cũng như giao thức https hoặc http.Paths: xác minh các điểm cuối lẻ tẻ (đường dẫn) trong API của công ty và những 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 đặc biệt quan trọng chứa thông tin API của bạn sẽ như ráng nào bằng đường truyền API, cách tiến hành (GET, POST, PUT...), request (query, path, body..), response API

API Host & Base URL

REST APIs có một URL các đại lý 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 vì schema, host, basePath

host: petstore.swagger.iobasePath: /v2schemes: - httpsTất cả API số đông được dựa trên phố URL này ví dụ:

Schema là giao thức truyền được API sử dụng. Swagger cung cấp 2 giao thức là http cùng https

paths: /pet: post:Khi đang khai báo băng thông đến API và thủ tục của API, chúng ta cần liên tục khai báo mang lại request input của API hotline là Parameters

Parameters

Trong Swagger, các tham số chuyển động API được xác minh trong phần thông số trong quan niệm hoạt động. Từng tham số gồm tên, kiểu quý giá (đối cùng với tham số giá trị nguyên thủy) hoặc lược trang bị (đối với câu chữ yêu cầu) và biểu đạt tùy chọn. Các dạng Parameters như thể :

query parameters, lấy ví dụ /users?role=admin.Tham số tầm nã vấn là một số loại tham số thông dụng nhất. Chúng mở ra ở cuối URL yêu cầu sau dấu chấm hỏi (?), Với những cặp thương hiệu = giá chỉ trị khác nhau được phân tách bóc bằng dấu và (&). Tham số truy vấn rất có thể được yêu ước và tùy chọn.

parameters: - in: query name: offset type: integer description: The number of items khổng lồ skip before starting khổng lồ collect the result set. - in: query name: limit type: integer description: The numbers of items to return.path parameters, lấy ví dụ như /users/id. Tham số đường truyền là những thành phần của đường dẫn URL hoàn toàn có thể khác nhau. Bọn chúng thường được áp dụng để trỏ mang lại một tài nguyên rõ ràng trong một cỗ sưu tập, ví dụ điển hình như người dùng được xác định bằng ID. Một URL hoàn toàn có thể có một trong những tham số con đường dẫn, mỗi tham số được biểu 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: OKheader parameters, ví dụ như X-MyHeader: Value. Một lệnh điện thoại tư vấn API có thể yêu ước gửi các tiêu đề tùy chỉnh cấu hình cùng với cùng một yêu cầu HTTP. Swagger có thể chấp nhận được bạn khẳng định tiêu đề yêu cầu tùy chỉnh thiết lập như trong: tham số tiêu đề. Ví dụ: mang sử, một cuộc hotline tới GET / ping yêu nhà xí đề X-Request-ID:paths: /ping: get: summary: Checks if the hệ thống is alive. Parameters: - in: header name: X-Request-ID type: string required: truebody parameters áp dụng trong the body toàn thân of POST, PUT và PATCH requests.Các yêu mong POST, PUT và PATCH hoàn toàn có thể có phần thân yêu ước (tải trọng), ví dụ như dữ liệu JSON hoặc XML. Theo thuật ngữ Swagger, câu chữ yêu mong được call là thông số nội dung. Chỉ có thể có một thông số nội dung, khoác dù chuyển động có thể có những tham số khác (đường dẫn, truy nã 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 khổng lồ create. Schema: type: object required: - userName properties: userName: type: string firstName: type: string lastName: type: stringform parameters sử dụng cho phần lớn request truyền lên những data ví như việc upload tệp tin chả hạnpaths: /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 đề nghị chỉ định các phản hồi cho tất cả các chuyển động API. Mỗi làm việc phải có tối thiểu một ý kiến đượ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ã tâm lý HTTP của chính nó và tài liệu được trả về vào nội dung phản hồi và / hoặc tiêu đề

paths: /ping: get: produces: - application/json responses: 200: description: OKTrong câu trả lời, mỗi định nghĩa phản hồi ban đầu bằng một mã trạng thái, ví dụ như 200 hoặc 404. Một vận động thường trả về một mã trạng thái thành công và một hoặc những trạng thái lỗi. Mỗi trạng thái ý kiến yêu cầu một mô tả.

Xem thêm: Phần 1: Language Review 6 7 8 Lớp 11 Sách Mới: Unit 6, Review Unit 6 7 8 Lớp 11

responses: 200: description: OK 400: description: Bad request. User ID must be an integer & bigger than 0. 401: description: Authorization information is missing or invalid. 404: description: A user with the specified ID was not found.Ngoài đều trạng thái status ra, bạn cũng có thể khai báo hầu như dạng 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ứ rất thú vị của Swagger cung cấp là $ref. Nó giúp chúng ta có thể sử dụng lại đều data cơ mà ta vẫn định nghĩa. Nó giúp tránh vấn đề trùng lặp tuyệt khai báo những 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 họ đã tìm hiểu cơ bản để viết được một tệp tin swagger định nghĩa API. Sau đó là một ví dụ mình đã viết ra:

Hy vọng nội dung bài viết của mình vẫn giúp các bạn hiểu và thực hiện Swagger một phương pháp tốt.Bài viết được tìm hiểu thêm từ : https://swagger.io/docs