Swagger Là Gì

Như bọn họ biết hiện nay việc cách tân và phát triển các vận dụng hay hệ thống đều cần sử dụng đến một thứ luôn luôn phải 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à ứng dụng khác. Nó là viết tắt của Application Programming Interface – bối cảnh lập trình ứng dụng. API cung ứng khả năng cung cấp khả năng truy xuất đến một tập những hàm xuất xắc dùng. Cùng từ đó hoàn toàn có thể trao đổi tài liệu giữa những ứng dụng.

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

Vậy nên bọn họ luôn phải một Tài liệu khuyên bảo API. Nó là 1 trong những nội dung kỹ thuật, nó chứa tất cả các tin tức được yêu ước để có thể làm câu hỏi với API, cùng với thông tin cụ thể về những tài nguyên, phương thức, những request với response, thông tin chứng thực, … được cung ứng bởi những hướng dẫn cùng ví dụ.Một lý lẽ rất phổ biến hiện nay để giúp làm một Tài liệu chỉ dẫn API chính là Swagger.

Swagger là gì

Swagger là 1 trong những bộ nguyên tắc mã mối cung cấp mở để gây ra OpenAPI specifications giúp bạn có thể thiết kế, kiến thiết tài liệu và sử dụng REST APIs.Swagger hỗ trợ 3 tools chính cho các developers :

Swagger-Editor : dùng để design lên các APIs trọn vẹn mới hoặc edit lại những APIs gồm sẵn thông sang một file config.Swagger-Codegen : dùng để generate ra code từ các file config tất cả sẵnSwagger-UI : dùng để làm generate ra file html,css,… từ là một file config.

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

Cấu trúc cơ bạn dạng của tệp tin Swagger

Đầu tiên 1 tệp tin swagger rất 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 bản Swagger . Phiên bạn dạng Swagger xác định cấu trúc tổng thể của quánh tả API - phần đông gì chúng ta có thể ghi lại và biện pháp bạn khắc ghi nó. Trong khi các thông tin chi tiết như tiêu đề, diễn tả hay version của bạn dạng api hiện tại tại cũng khá được khai báo tại đây.

Xem thêm: Tại Sao Con Gái Khó Lên Đỉnh Và Cách Điều Trị, Tin Vui Cho Phụ Nữ Khó 'Lên Đỉnh'

Base Url: Nơi các bạn sẽ định nghĩa host của server, đường truyền 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 chưa có người yêu (đườ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 những điểm cuối này. Và đây là phần đặc biệt quan trọng chứa tin tức 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 bao gồm một URL các đại lý mà những đường dẫn điểm cuối được nối vào. Đường url này được định nghĩa vị schema, host, basePath

host: petstore.swagger.iobasePath: /v2schemes: - httpsTất cả API đa số được dựa trên đường 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 với https

paths: /pet: post:Khi đã khai báo băng thông đến API và cách thức của API, bọn họ cần thường xuyên khai báo mang đến request đầu vào của API gọi là Parameters

Parameters

Trong Swagger, các tham số vận động API được khẳng định trong phần thông số trong định nghĩa hoạt động. Mỗi tham số tất cả tên, kiểu quý giá (đối cùng với tham số quý giá nguyên thủy) hoặc lược vật (đối với văn bản yêu cầu) và biểu đạt tùy chọn. Các dạng Parameters như là :

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

parameters: - in: query name: offset type: integer description: The number of items lớn skip before starting khổng lồ collect the result set. - in: query name: limit type: integer description: The numbers of items khổng lồ 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 có thể khác nhau. Bọn chúng thường được sử dụng để trỏ cho một tài nguyên rõ ràng trong một bộ sưu tập, chẳng hạn như người tiêu dùng được xác định bằng ID. Một URL rất có thể có một trong những tham số đường dẫn, từng tham số được thể hiện bằng vết ngoặc nhọn .paths: /users/id: get: parameters: - in: path name: id # chú ý the name is the same as in the path required: true type: integer minimum: 1 description: The user ID. Responses: 200: description: OKheader parameters, lấy một ví dụ X-MyHeader: Value. Một lệnh hotline API hoàn toàn có thể yêu cầu gửi những tiêu đề tùy chỉnh cùng với cùng một yêu cầu HTTP. Swagger chất nhận được bạn xác minh tiêu đề yêu thương cầu tùy chỉnh cấu hình như trong: tham số tiêu đề. Ví dụ: mang sử, một cuộc điện thoại tư vấn tới GET / ping yêu chuồng tiêu đề 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 toàn thân of POST, PUT và PATCH requests.Các yêu mong POST, PUT và PATCH 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, nội dung yêu ước được gọi là tham số nội dung. Chỉ hoàn toàn có thể có một tham số nội dung, mang dù vận động 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 name: user description: The user to create. Schema: type: object required: - userName properties: userName: type: string firstName: type: string lastName: type: stringform parameters thực hiện cho phần lớn request truyền lên nhiều data ví dụ 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 yêu cầu chỉ định các phản hồi cho toàn bộ các vận động API. Mỗi thao tác phải có tối thiểu một phản hồi được xác định, thường là một trong những phản hồi thành công. Phản hồi được xác minh bằng mã tâm trạng HTTP của chính nó và tài liệu được trả về vào nội dung bình luận và / hoặc tiêu đề

paths: /ping: get: produces: - application/json responses: 200: description: OKTrong câu trả lời, mỗi có mang phản hồi ban đầu bằng một mã trạng thái, ví dụ như 200 hoặc 404. Một chuyển động thường trả về một mã trạng thái thành công xuất sắc và một hoặc những trạng thái lỗi. Mỗi trạng thái bình luận yêu cầu một tế bào 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 đa số trạng thái status ra, bạn có thể khai báo đông đảo dạng dữ liệu mà API vẫn 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 lôi cuốn của Swagger hỗ trợ là $ref. Nó giúp chúng ta cũng có thể sử dụng lại hồ hết data mà ta vẫn định nghĩa. Nó giúp tránh việc trùng lặp tốt 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ò cơ bản để viết được một file swagger định nghĩa API. Sau đây là một ví dụ tôi đã viết ra:

*

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