Như bọn họ biết hiện thời việc cải tiến và phát triển những vận dụng tuyệt khối hệ thống những buộc phải sử dụng đến một trang bị không thể thiếu là API.Nó là những thủ tục, giao thức liên kết với những thỏng viện với vận dụng khác. Nó là viết tắt của Application Programming Interface – giao diện thiết kế vận dụng. API hỗ trợ kỹ năng hỗ trợ kỹ năng truy vấn xuất cho một tập các hàm xuất xắc sử dụng. Và từ kia rất có thể trao đổi tài liệu thân những ứng dụng.

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

Vậy đề xuất bọn họ luôn nên một Tài liệu trả lời API. Nó là một nội dung nghệ thuật, nó chứa toàn bộ các ban bố được tận hưởng để hoàn toàn có thể thao tác với API, với ban bố cụ thể về những tài nguyên, phương thức, những request và response, biết tin xác thực, … được cung cấp bởi các gợi ý với ví dụ.Một luật siêu phổ biến hiện thời sẽ giúp làm một Tài liệu hướng dẫn API đó là Swagger.

Swagger là gì

Swagger là 1 cỗ qui định mã nguồn msinh hoạt để chế tạo OpenAPI specifications góp bạn cũng có thể thi công, tạo tư liệu với sử dụng REST APIs.Swagger hỗ trợ 3 tools thiết yếu cho những developers :

Swagger-Editor : dùng để làm kiến thiết lên các APIs trọn vẹn new hoặc edit lại những APIs có sẵn thông qua một tệp tin config.Swagger-Codegen : dùng để generate ra code từ bỏ những tệp tin config gồm sẵnSwagger-UI : dùng làm generate ra file html,css,… từ 1 file config.

Trong các tools bên trên, Swagger UI được thực hiện những tuyệt nhất, nó giúp sinh ra bối cảnh mang đến tư liệu từ file config dưới chuẩn chỉnh OpenAPI. Giao diện được chỉ ra ví dụ với tường minc. Dễ dàng gọi đọc cho tất cả lập trình sẵn viên lẫn người dùng. Sử dụng tệp tin config nhưng lại hoàn toàn tách bóc biệt tác vụ cùng nhau. Trong bài xích này mình đã trình làng Swagger phiên bản 2.0 .

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

Trước tiên 1 tệp tin swagger rất có thể viết bằng JSON hoặc YAML.

Metadata: Mọi thông số kỹ thuật chuyên môn của Swagger phần lớn ban đầu với phiên phiên bản Swagger . Phiên bản Swagger xác định cấu tạo toàn diện của đặc tả API - phần đa gì chúng ta cũng có thể khắc ghi và phương pháp các bạn khắc ghi nó. Bên cạnh đó những đọc tin cụ thể như tiêu đề, thể hiện xuất xắc version của bản api hiện thời cũng khá được knhị báo tại trên đây.

Xem thêm: Cách Làm Phở Chiên Giòn Rụm, Thơm Ngon, Cực Lạ Miệng, Cách Làm Bánh Phở Chiên Giòn

Base Url: Nơi bạn sẽ định nghĩa host của server, đường dẫn cơ bạn dạng cũng giống như giao thức https hoặc http.Paths: xác định các điểm cuối đơn côi (đường dẫn) trong API của khách hàng cùng các thủ tục HTTP (hoạt động) được cung ứng do những điểm cuối này. Và đó là phần đặc trưng cất biết tin API của bạn sẽ ra làm sao bằng băng thông API, cách thức (GET, POST, PUT...), request (query, path, body..), response API

API Host and Base URL

REST APIs tất cả một URL cửa hàng mà những đường dẫn điểm cuối được nối vào. Đường url này được quan niệm bởi vì schema, host, basePath

host: petstore.swagger.iobasePath: /v2schemes: - httpsTất cả API gần như được dựa trên tuyế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 cùng https

paths: /pet: post:Lúc vẫn knhị báo đường truyền mang lại API cùng cách tiến hành của API, bọn họ nên liên tục knhì báo cho request đầu vào của API Gọi là Parameters

Parameters

Trong Swagger, các tđê mê số vận động API được xác định trong phần tđắm đuối số vào khái niệm vận động. Mỗi tđê mê số mang tên, vẻ bên ngoài giá trị (so với tsi số quý giá nguyên thủy) hoặc lược trang bị (so với câu chữ yêu cầu) với diễn 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à một số loại tmê man số phổ biến nhất. Chúng lộ diện sinh sống cuối URL tận hưởng sau vết chấm hỏi (?), Với những cặp thương hiệu = giá trị khác nhau được phân bóc bởi vết và (&). Tsi mê số truy vấn hoàn toàn có thể được từng trải và tùy lựa chọn.

parameters: - in: query name: offset type: integer description: The number of items to 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, ví dụ /users/id. Tđắm say số đường truyền là những nguyên tố của đường dẫn URL có thể không giống nhau. Chúng hay được sử dụng để trỏ mang đến một tài nguyên ổn cụ thể trong một bộ sưu tầm, chẳng hạn như người dùng được khẳng định bằng ID. Một URL có thể bao gồm một số trong những tyêu thích số đường truyền, từng tyêu thích số được biểu lộ bằng dấu ngoặc nhọn .paths: /users/id: get: parameters: - in: path name: id # cảnh báo 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ụ X-MyHeader: Value. Một lệnh điện thoại tư vấn API có thể thưởng thức gửi những tiêu đề tùy chỉnh thiết lập cùng với một trải nghiệm HTTP. Swagger có thể chấp nhận được các bạn xác định title kinh nghiệm thiết lập nlỗi trong: tham số title. Ví dụ: trả sử, một cuộc call cho tới GET / ping yêu thương nhà cầu đề X-Request-ID:paths: /ping: get: summary: Checks if the server is alive sầu. parameters: - in: header name: X-Request-ID type: string required: truebody toàn thân parameters áp dụng trong the body of POST, PUT và PATCH requests.Các yên cầu POST, PUT cùng PATCH hoàn toàn có thể gồm phần thân thử dùng (download trọng), ví dụ như tài liệu JSON hoặc XML. Theo thuật ngữ Swagger, câu chữ trải nghiệm được Điện thoại tư vấn là tsay đắm số câu chữ. Chỉ hoàn toàn có thể có một ttê mê số văn bản, tuy vậy hoạt động rất có thể gồm các tmê mẩn số không giống (đường dẫn, tróc nã vấn, tiêu đề).paths: /users: post: summary: Creates a new user. consumes: - application/json parameters: - in: body name: user description: The user to lớn create. schema: type: object required: - userName properties: userName: type: string firstName: type: string lastName: type: stringform parameters sử dụng mang đến số đông request truyền lên các data ví dụ như bài toán upload file 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 phải hướng đẫn các phản hồi cho tất cả các vận động API. Mỗi thao tác cần bao gồm tối thiểu một đánh giá được xác minh, thường xuyên là một trong đánh giá thành công xuất sắc. Phản hồi được xác định bởi mã tâm lý HTTPhường của chính nó với dữ liệu được trả về trong văn bản phản hồi và / hoặc tiêu đề

paths: /ping: get: produces: - application/json responses: 200: description: OKTrong câu trả lời, từng tư tưởng phản hồi bắt đầu bằng một mã tâm trạng, ví dụ như 200 hoặc 404. Một chuyển động hay trả về một mã tinh thần thành công xuất sắc với một hoặc nhiều tâm trạng lỗi. Mỗi tâm trạng ý kiến yên cầu một bộc lộ.

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 mọi tinh thần status ra, chúng ta có thể knhì báo gần như dạng dữ liệu cơ 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 vật dụng rất hấp dẫn của Swagger cung cấp là $ref. Nó giúp bạn có thể áp dụng lại phần nhiều data nhưng mà ta sẽ định nghĩa. Nó góp rời vấn đề giống nhau giỏi 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ỏng trên họ vẫn khám phá cơ bạn dạng nhằm viết được một tệp tin swagger định nghĩa API. Sau đấy là một ví dụ mình đã viết ra:

*

Hy vọng bài viết của bản thân sẽ giúp đỡ chúng ta đọc với thực hiện Swagger một biện pháp tốt.Bài viết được tìm hiểu thêm trường đoản cú : https://swagger.io/docs