Như chúng ta đã biết, việc phát triển một ứng dụng hoặc hệ thống ngày nay yêu cầu sử dụng một API tích hợp. Nó là một phương pháp và 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 quyền truy cập vào một tập hợp các chức năng thường được sử dụng. Từ đó dữ liệu có thể được trao đổi giữa các ứng dụng.
Vì vậy, chúng tôi luôn cần một tài liệu API. Đó là nội dung kỹ thuật, chứa tất cả thông tin cần thiết để có thể sử dụng API, bao gồm chi tiết về tài nguyên, phương pháp, yêu cầu và phản hồi, thông tin xác thực, v.v., được hỗ trợ bởi các hướng dẫn và ví dụ. Swagger là một công cụ rất phổ biến hiện nay để trợ giúp về tài liệu API.
Swagger là gì
Swagger là một công cụ mở dùng để xây dựng bộ công cụ nguồn của đặc tả OpenAPI để chúng ta có thể thiết kế, ghi lại và sử dụng API REST . Swagger cung cấp 3 công cụ chính cho nhà phát triển:
- Swagger-Editor : Dùng để thiết kế API hoàn toàn mới hoặc chỉnh sửa API hiện có thông qua 1 tệp cấu hình.
- Swagger-Codegen: Được sử dụng để tạo mã từ các tệp cấu hình có sẵn
- Swagger-UI: Được sử dụng để tạo từ html cấu hình , css, …
Trong số các công cụ trên, Swagger UI được sử dụng nhiều nhất, nó giúp tạo giao diện tài liệu từ các tệp cấu hình theo tiêu chuẩn OpenAPI. Giao diện hiển thị rõ ràng, rành mạch. Dễ dàng cho các lập trình viên và người dùng để đọc. Sử dụng các tệp cấu hình, nhưng tách biệt hoàn toàn các tác vụ. Trong bài viết này, tôi sẽ giới thiệu phiên bản Swagger 2.0.
Cấu trúc cơ bản của tệp Swagger
Đầu tiên, bạn có thể viết tệp swagger bằng JSON hoặc YAML.
- Siêu dữ liệu: Tất cả các thông số kỹ thuật của Swagger đều bắt đầu bằng một phiên bản Swagger. Bản phát hành Swagger xác định cấu trúc tổng thể của đặc tả API – bạn có thể ghi lại những gì và cách ghi lại nó. Ngoài ra, các chi tiết như tiêu đề, mô tả hoặc phiên bản của api hiện tại được khai báo tại đây.
- Url cơ sở: Tại đây, bạn sẽ xác định máy chủ lưu trữ, đường dẫn cơ bản và giao thức https hoặc http của máy chủ.
- Tiêu dùng, sản xuất: Xác định các loại MiME được API hỗ trợ
- Đường dẫn: Xác định từng điểm cuối (đường dẫn) trong API và các phương thức HTTP (hoạt động) được hỗ trợ bởi các điểm cuối này. Đây là phần thông tin quan trọng chứa đường dẫn API, phương thức (GET, POST, PUT…), yêu cầu (query, path, body…), phản hồi API
Máy chủ API và URL cơ sở
API REST có một URL cơ sở được nối với đường dẫn điểm cuối. Url này được xác định bởi schema, host, basePath
host: petstore.swagger.io basePath: /v2 scheme: – https
Tất cả các API đều dựa trên URL này, ví dụ:
- Schema là giao thức truyền tải được sử dụng bởi API. Swagger hỗ trợ 2 giao thức: http và https
Lược đồ: – http – https
- host là tên miền hoặc địa chỉ IP (IPv4) của máy chủ cung cấp API. Nó có thể chứa số cổng nếu nó 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ỉ có thể là máy chủ, 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 thư mục gốc của máy chủ. Nó phải bắt đầu bằng dấu gạch chéo /. Nếu bạn không chỉ định basePath, mặc định là /, nghĩa là tất cả các đường dẫn bắt đầu từ trang nguồn
/v2 /api/v2 /
Đường dẫn và Thao tác
là các điểm cuối (tài nguyên) tiếp xúc với API của bạn, chẳng hạn như /pet và đang 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.
đường dẫn: /pet: post:
Sau khi chúng tôi khai báo đường dẫn của API và các phương thức của nó, chúng tôi cần tiếp tục khai báo lệnh gọi đầu vào yêu cầu API Tham số
Tham số
Trong Swagger, tham số hành động API được xác định trong phần tham số của định nghĩa hoạt động. Mỗi tham số có tên, loại giá trị (đối với tham số giá trị thô) hoặc lược đồ (đối với nội dung yêu cầu) và mô tả tùy chọn. Các tham số như:
- Tham số truy vấn 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 sau dấu chấm hỏi (?) ở cuối URL yêu cầu, với các cặp tên=giá trị riêng biệt được phân tách bằng dấu và (&).Tham số truy vấn có thể được yêu cầu hoặc tùy chọn.
Tham số: -in: tên truy vấn: loại offset: mô tả số nguyên: Số mục cần bỏ qua trước khi bắt đầu thu thập tập kết quả. – in: tên truy vấn: loại giới hạn: mô tả số nguyên: số mục cần trả về.
- Tham số đường dẫn, chẳng hạn như /users/{id}. Tham số đường dẫn là các thành phần của đường dẫn URL có thể thay đổi. Chúng thường được sử dụng để trỏ đến một tài nguyên cụ thể trong bộ sưu tập, chẳng hạn như người dùng được xác định bởi ID. Một URL có thể có nhiều tham số đường dẫn, mỗi tham số đường dẫn được biểu thị bằng dấu ngoặc nhọn {}.
đường dẫn: /users/{id}: get: tham số: – trong: tên đường dẫn: id # Lưu ý rằng tên giống với đường dẫn mong muốn: kiểu đúng: số nguyên Giá trị tối thiểu: 1 mô tả: người dùng giấy tờ tùy thân . phản hồi: 200: mô tả: OK
- tham số tiêu đề Ví dụ: X-MyHeader: Value. Lệnh gọi API có thể yêu cầu gửi tiêu đề tùy chỉnh cùng với yêu cầu HTTP. Swagger cho phép bạn xác định các tiêu đề yêu cầu tùy chỉnh trong tham số :header. Ví dụ: lệnh gọi GET /ping yêu cầu tiêu đề X-Request-ID:
đường dẫn: /ping: get: summary: Kiểm tra xem máy chủ có hoạt động không. Tham số: -in: tên tiêu đề: X -Loại ID yêu cầu: chuỗi bắt buộc: true
- tham số nội dung Nội dung cho các yêu cầu POST, PUT và PATCH. 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. Trong thuật ngữ Swagger, nội dung yêu cầu được gọi là tham số nội dung. Có thể chỉ có một tham số nội dung, mặc dù các hoạt động có thể có các tham số khác (đường dẫn, truy vấn, tiêu đề).
paths: /users: post: summary: Tạo người dùng mới. Tiêu thụ: – application/json Tham số: – trong: tên cơ thể: mô tả người dùng: người dùng để tạo. lược đồ: loại: đối tượng bắt buộc: – thuộc tính userName: userName: loại: chuỗi FirstName: loại: chuỗi họ: loại: chuỗi
- thông số biểu mẫu Yêu cầu tải lên để truyền nhiều tệp dữ liệu
path: /survey: post: summary: Khảo sát mẫu. Tiêu thụ: – application/x-www-form-urlencoded Tham số: – trong: formData name: name type: string description: Tên của một người. – in: form Tên dữ liệu: fav_number Loại: số Mô tả: Số yêu thích của một người.
API phản hồi
API cần chỉ định phản hồi cho tất cả các hoạt động của API. Mọi hoạt động phải xác định ít nhất một phản hồi, thường là phản hồi thành công. Phản hồi được xác định bằng mã trạng thái HTTP và dữ liệu được trả về trong nội dung phản hồi và/hoặc tiêu đề
đường dẫn: /ping: get: tạo: – phản hồi của ứng dụng/json: 200: mô tả: OK
Trong câu trả lời, per 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. Các hoạt động 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ả.
phản hồi: 200: mô tả: OK 400: mô tả: Yêu cầu không hợp lệ. ID người dùng phải là một số nguyên lớn hơn 0. 401: Mô tả: Thông tin ủy quyền bị thiếu hoặc không hợp lệ. 404: Mô tả: Không tìm thấy người dùng nào có ID được chỉ định.
Ngoài trạng thái trạng thái, chúng ta cũng có thể khai báo loại dữ liệu mà API sẽ trả về
Phản hồi: 200: mô tả: lược đồ đối tượng người dùng: loại: thuộc tính đối tượng: id: loại: số nguyên mô tả: userid.user tên: loại: chuỗi mô tả: tên người dùng.
Một điều thú vị mà Swagger hỗ trợ là $ref. Nó giúp chúng tôi tái sử dụng dữ liệu chúng tôi xác định. Nó giúp tránh trùng lặp hoặc khai báo nhiều lần.
Phản hồi: 200: mô tả: giản đồ đối tượng pet: $ref: ‘#/definitions/Pet’ “405”: description: định nghĩa “đầu vào không hợp lệ”: pet: type: “object” properties: id: type: ” integer” name: type: “string” example: “doggie” status: type: “string” description: “trạng thái thú cưng trong cửa hàng”
Viết tệp swagger định nghĩa API dựa trên kiến thức cơ bản chúng ta đã học ở trên. Đây là một ví dụ tôi đã viết:
swagger: “2.0” info: description: “demo” version: “1.0.0” title: “Swagger Petstore” Host: “petstore.swagger.io” basePath: “/v2 ” lược đồ: – “https” – “http” đường dẫn: /pet: bài đăng: thẻ: – “thú cưng” tóm tắt: “Thêm thú cưng mới vào cửa hàng” mô tả: “” operationId: “addPet” tiêu thụ: – “ứng dụng / json” – “application/xml” mang lại: – “application/xml” – “application/json” Tham số: – trong: tên “body”: mô tả “body”: “Đối tượng thú cưng cần được thêm vào cửa hàng” bắt buộc : true Lược đồ: Loại: Thuộc tính đối tượng: Tên: Loại: Chuỗi Phản hồi: “200”: Mô tả: “Thành công” “405”: Mô tả: “Đầu vào không hợp lệ” /pets/{id}:get: Thẻ: – “thú cưng” tóm tắt: “Nhận thú cưng của cửa hàng” Mô tả: hoạt động “Nhận thú cưng của cửa hàng”Id: “getPets” Tiêu thụ: – “application/json” Sản xuất: – “application/json” Tham số: – trong: tên đường dẫn: loại id: yêu cầu số nguyên : true Mô tả: ID số của người dùng cần tìm nạp.phản hồi: 200: mô tả: lược đồ đối tượng pet: $ref: ‘#/definitions/Pet’ “405”: mô tả: định nghĩa “Đầu vào không hợp lệ”: pet: type: thuộc tính “đối tượng”: id: type: tên “số nguyên”: type: “string” example: “doggie” status: type: “string” description: “trạng thái thú cưng trong cửa hàng”
Tôi hy vọng bài viết của mình có thể giúp bạn hiểu và sử dụng thành thạo Swagger. Bài viết được tham khảo từ: https://swagger.io/docs
.