nút
Các tham số API thường có cấu trúc phức tạp, với một điểm cuối duy nhất hỗ trợ nhiều tổ hợp tham số khác nhau. Ví dụ, một điểm cuối đăng nhập có thể hỗ trợ xác thực bằng tên người dùng-mật khẩu, xác thực bằng email-mật khẩu, hoặc mã xác minh số điện thoại. Các điểm cuối thanh toán có thể cung cấp nhiều phương thức khác nhau như thẻ tín dụng, WeChat Pay, hoặc Alipay, mỗi phương thức yêu cầu các trường khác nhau.
Các phương pháp tài liệu hóa API truyền thống thường chỉ liệt kê tất cả các trường có thể có và sử dụng các mô tả văn bản như "chọn các trường khác nhau dựa trên các kịch bản khác nhau." Cách tiếp cận này không chính xác cũng không thân thiện với nhà phát triển, thường dẫn đến sự nhầm lẫn. Apidog hỗ trợ các tính năng oneOf, anyOf, và allOf của JSON Schema, cho phép bạn mô tả chính xác các cấu trúc dữ liệu tổng hợp phức tạp này trong tài liệu API của mình.
Tìm hiểu Ba Chế độ Kết hợp
Trong JSON Schema, oneOf, anyOf, và allOf được sử dụng để kết hợp nhiều lược đồ con, nhưng chúng có ý nghĩa logic khác nhau:
- allOf: Kết hợp nhiều quy tắc, yêu cầu tất cả phải khớp
- anyOf: Yêu cầu ít nhất một khớp, nhiều khớp được chấp nhận
- oneOf: Phải khớp chính xác một lược đồ, khớp không hoặc nhiều lược đồ sẽ thất bại
Thiết lập Chế độ Kết hợp trong Apidog
Apidog cung cấp hai cách để sử dụng các chế độ kết hợp này:
Cách tiếp cận Trình chỉnh sửa trực quan
Phương pháp đầu tiên sử dụng bảng chỉnh sửa trực quan. Trong dự án của bạn, nhấp vào "Mô hình dữ liệu" để tạo một mô hình mới, sau đó tìm "Chế độ kết hợp" trong lựa chọn loại. Chọn chế độ oneOf, anyOf, hoặc allOf cần thiết, sau đó xác định cấu trúc dữ liệu cụ thể cho từng lược đồ con.
Trình chỉnh sửa mã JSON Schema
Cách tiếp cận thứ hai liên quan đến việc chỉnh sửa trực tiếp mã JSON Schema. Trong bảng chỉnh sửa mô hình dữ liệu, bạn có thể chuyển sang chế độ mã và viết JSON Schema trực tiếp để xác định các mẫu kết hợp logic này. Phương pháp này trực tiếp hơn đối với các nhà phát triển quen thuộc với JSON Schema.
Áp dụng các Mẫu này trong Điểm cuối API
Khi bạn đã xác định các mô hình dữ liệu của mình, bạn có thể sử dụng chúng trong tài liệu API của mình. Khi chỉnh sửa các tham số yêu cầu giao diện, chọn loại Body là JSON, sau đó trong phần cấu trúc dữ liệu, bạn có thể tham chiếu "Mô hình dữ liệu" bạn vừa tạo, hoặc trực tiếp chọn "Chế độ kết hợp" để xác định cấu trúc tham số phức tạp.
Nguyên tắc tương tự áp dụng cho các định nghĩa dữ liệu phản hồi. Khi thêm các ví dụ phản hồi trong phần phản hồi trả về, bạn có thể sử dụng các chế độ kết hợp để mô tả các định dạng phản hồi cho các kịch bản khác nhau. Bằng cách này, các nhà phát triển có thể hiểu rõ ràng cấu trúc dữ liệu nào sẽ được trả về trong các tình huống khác nhau.
Các Trường hợp Sử dụng Thực tế
allOf: Kết hợp Nhiều Cấu trúc
allOf kết hợp nhiều cấu trúc lại với nhau - nó không phải là về việc lựa chọn, mà là về việc xếp chồng. allOf không thay đổi hệ thống phân cấp trường; tất cả các trường cuối cùng đều nằm trong cùng một đối tượng. Nó chỉ đơn giản là xếp chồng nhiều quy tắc trên cùng một dữ liệu. Hãy nghĩ về nó như "AND logic" - tất cả các ràng buộc của cấu trúc con phải được thỏa mãn.
Ví dụ, JSON Schema này:
{
"allOf": [
{
"description": "Thông tin người dùng cơ bản",
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
},
{
"description": "Thông tin liên hệ",
"type": "object",
"properties": {
"email": { "type": "string", "format": "email" },
"phone": { "type": "string" }
},
"required": ["email"]
}
]
}
Lược đồ này có nghĩa là: dữ liệu cuối cùng phải đồng thời thỏa mãn cả cấu trúc "thông tin người dùng cơ bản" và "thông tin liên hệ".
Nói cách khác, body yêu cầu phải bao gồm id, name, và email, trong khi phone là tùy chọn.
Dữ liệu hợp lệ:
{
"id": 1001,
"name": "John Doe",
"email": "john@example.com",
"phone": "1-800-000-0000"
}
Dữ liệu không hợp lệ:
{
"id": 1001,
"name": "John Doe"
}
Cái này thiếu trường email bắt buộc và không thỏa mãn cấu trúc thứ hai.
Cách tiếp cận này phù hợp để chia tách các đối tượng phức tạp. Thông tin người dùng, chi tiết đơn hàng, các mục cấu hình, v.v., đều có thể được chia thành các cấu trúc độc lập theo các module chức năng, sau đó được kết hợp bằng cách sử dụng allOf. Các giao diện khác cần một phần của các cấu trúc này có thể tham chiếu trực tiếp mà không cần định nghĩa lại.
anyOf: Thỏa mãn ít nhất một Điều kiện
anyOf liệt kê nhiều cấu trúc có thể có, và dữ liệu được coi là hợp lệ miễn là nó tuân thủ ít nhất một trong số chúng. Nó không quan tâm liệu nhiều điều kiện có được thỏa mãn hay không, cũng không yêu cầu khớp duy nhất.
Ví dụ, một trường định danh có thể là email hoặc số điện thoại. Hai định dạng này khác biệt rõ rệt, nhưng cả hai đều thuộc loại "thông tin đăng nhập người dùng."
Bạn có thể sử dụng anyOf để diễn đạt rõ ràng ý định "có thể là A hoặc B" này:
{
"type": "object",
"properties": {
"identifier": {
"description": "Định danh người dùng: có thể là email hoặc số điện thoại",
"anyOf": [
{
"title": "Định dạng email",
"description": "Phải là một địa chỉ email hợp lệ",
"type": "string",
"format": "email"
},
{
"title": "Định dạng số điện thoại",
"description": "Phải là một số điện thoại quốc tế hợp lệ",
"type": "string",
"pattern": "^\\+?[1-9]\\d{1,14}$"
}
]
},
"password": {
"type": "string",
"minLength": 6,
"description": "Mật khẩu đăng nhập, ít nhất 6 ký tự"
}
},
"required": ["identifier", "password"],
"description": "Tham số yêu cầu đăng nhập người dùng"
}
Cấu trúc này có nghĩa là: định danh là một chuỗi được coi là hợp lệ miễn là nó thỏa mãn định dạng email hoặc định dạng số điện thoại.
Dữ liệu hợp lệ:
{
"identifier": "test@example.com",
"password": "123456"
}
{
"identifier": "+1-800-000-0000",
"password": "123456"
}
Dữ liệu không hợp lệ:
{
"identifier": "abc",
"password": "123456"
}
"abc" không phải là email cũng không phải là định dạng số điện thoại hợp lệ, không thỏa mãn điều kiện nào.
oneOf: Chọn Chính xác một Tùy chọn
oneOf liệt kê nhiều cấu trúc có thể có, và dữ liệu phải tuân thủ chính xác một trong số chúng. Nó nhấn mạnh tính độc quyền - bạn chỉ có thể chọn một, không hơn, không kém.
Ví dụ, các phương thức thanh toán: để hoàn tất thanh toán, người dùng phải chọn một trong thẻ tín dụng, WeChat Pay, hoặc Alipay, nhưng không thể sử dụng hai phương thức đồng thời, cũng không thể không chọn cái nào. Bạn có thể định nghĩa logic "chọn một" này bằng cách sử dụng oneOf:
{
"properties": {
"paymentMethod": {
"description": "Phương thức thanh toán, phải chọn chính xác một",
"oneOf": [
{
"title": "Thanh toán bằng thẻ tín dụng",
"description": "Thanh toán bằng thẻ tín dụng, yêu cầu số thẻ và ngày hết hạn",
"type": "object",
"properties": {
"type": { "const": "credit_card" },
"cardNumber": { "type": "string" },
"expiryDate": { "type": "string" }
},
"required": ["type", "cardNumber", "expiryDate"],
"additionalProperties": false
},
{
"title": "Thanh toán WeChat",
"description": "Thanh toán qua WeChat, yêu cầu openid của người dùng",
"type": "object",
"properties": {
"type": { "const": "wechat" },
"openid": { "type": "string" }
},
"required": ["type", "openid"],
"additionalProperties": false
},
{
"title": "Thanh toán Alipay",
"description": "Thanh toán qua Alipay, yêu cầu ID tài khoản",
"type": "object",
"properties": {
"type": { "const": "alipay" },
"accountId": { "type": "string" }
},
"required": ["type", "accountId"],
"additionalProperties": false
}
]
}
}
}
Định nghĩa này có nghĩa là: paymentMethod là một đối tượng chỉ có thể khớp với một trong ba cấu trúc con.
Ví dụ hợp lệ:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123456"
}
}
{
"paymentMethod": {
"type": "credit_card",
"cardNumber": "4111111111111111",
"expiryDate": "12/25"
}
}
Ví dụ không hợp lệ:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123",
"accountId": "2088102"
}
}
Mặc dù loại là "wechat", sự hiện diện của accountId có thể khiến nó khớp với nhiều cấu trúc, gây ra lỗi oneOf. Việc thêm "additionalProperties": false ngăn chặn sự nhầm lẫn này (nghĩa là không cho phép các trường bổ sung), đảm bảo mỗi cấu trúc chỉ cho phép các trường được định nghĩa riêng của nó. Apidog hỗ trợ cấu hình trực quan cho additionalProperties.
Khi bạn cần đưa ra các lựa chọn độc quyền giữa nhiều loại khác biệt, oneOf là cách trực tiếp và đáng tin cậy nhất để diễn đạt điều này.
Chọn Chế độ Kết hợp Phù hợp
Việc lựa chọn chế độ kết hợp chủ yếu phụ thuộc vào logic nghiệp vụ của bạn:
- Sử dụng allOf khi bạn cần kết hợp và kế thừa nhiều mẫu
- Sử dụng anyOf khi bạn cần các tổ hợp tùy chọn linh hoạt
- Sử dụng oneOf khi bạn cần các lựa chọn độc quyền nghiêm ngặt
Hiểu rõ vai trò tương ứng của chúng cho phép tài liệu API của bạn mô tả chính xác các cấu trúc dữ liệu phức tạp, giúp người dùng giao diện hiểu ngay cách truyền tham số.
Kết luận
Hỗ trợ JSON Schema toàn diện của Apidog trao quyền cho các nhà phát triển tạo tài liệu API chính xác, rõ ràng cho cả những cấu trúc tham số phức tạp nhất. Bằng cách tận dụng các kết hợp oneOf, anyOf và allOf, bạn có thể loại bỏ sự mơ hồ và cung cấp hướng dẫn rõ ràng cho người tiêu dùng API.
Sẵn sàng trải nghiệm sức mạnh của tài liệu API nâng cao? Hãy thử Apidog ngay hôm nay và xem việc quản lý các tham số API phức tạp với độ chính xác và rõ ràng trở nên dễ dàng như thế nào.
nút