Xây dựng Schema

Sử dụng Schema Editor

Schema Editor là một công cụ mạnh mẽ hỗ trợ thiết kế và mô hình hóa các cấu trúc dữ liệu mà API của bạn sử dụng. Công cụ này dựa trên JSON Schema và được sử dụng để thiết kế các cấu trúc dữ liệu JSON hoặc XML.

Sử dụng Schema Editor để:

Phát triển body của yêu cầu và phản hồi API được điều chỉnh cho các endpoint API cụ thể.

Xây dựng các mô hình dữ liệu có thể áp dụng trên một hoặc nhiều API.

Mọi schema đều bắt đầu bằng một đối tượng gốc. Để xây dựng một schema, hãy thêm các thuộc tính vào đối tượng gốc này.

Thêm thuộc tính

Nhấp vào dấu + (Thêm một nút con) bên cạnh đối tượng gốc để đưa vào các thuộc tính mới.

Đặt tên cho thuộc tính

Nhập tên (hoặc khóa) cho thuộc tính.

Chọn loại thuộc tính

Chọn các kiểu dữ liệu phổ biến hoặc chọn tham chiếu đến các schema đã được định nghĩa trước.

Cài đặt nâng cao

Sử dụng Type Editor để gán các kiểu dữ liệu, chẳng hạn như giá trị mặc định và định dạng, cho từng thuộc tính.

Quản lý thuộc tính

Sắp xếp lại các thuộc tính bằng cách di chuyển, sao chép hoặc xóa chúng. Bạn cũng có thể bổ sung mô tả cho các thuộc tính và đánh dấu chúng là bắt buộc.

Phương pháp thay thế

Bạn cũng có thể tạo schema mới bằng cách nhập từ bảng cơ sở dữ liệu hoặc tệp JSON schema. Tìm hiểu thêm về Tạo schema từ JSON, v.v..

Loại thuộc tính

Phù hợp với tiêu chuẩn JSON Schema, Apidog Schema Editor hỗ trợ các kiểu dữ liệu cơ bản sau:

Loại	Mô tả
null	Đại diện cho một giá trị JSON "null".
boolean	Đại diện cho giá trị "true" hoặc "false", tương ứng với giá trị JSON "true" hoặc "false".
object	Đại diện cho một tập hợp không có thứ tự gồm các cặp khóa-giá trị, tương ứng với giá trị JSON "object".
array	Đại diện cho một danh sách giá trị có thứ tự, tương ứng với giá trị JSON "array".
number	Đại diện cho một giá trị số thập phân cơ số 10 có độ chính xác tùy ý, tương ứng với giá trị JSON "number".
string	Đại diện cho một chuỗi ký tự Unicode, tương ứng với giá trị JSON "string".

Kiểu dữ liệu Array

Khi sử dụng kiểu dữ liệu array, một thuộc tính cấp con ITEMS sẽ được tự động tạo. Thuộc tính này chỉ định kiểu dữ liệu của các phần tử trong mảng.

Ngoài các cấu trúc dữ liệu tiêu chuẩn đã đề cập ở trên, Apidog Schema Editor cũng hỗ trợ các nội dung sau:

Tham chiếu schema khác: Khả năng tham chiếu và tái sử dụng các schema được định nghĩa ở nơi khác trong tài liệu API.

any: Đại diện cho một giá trị có thể thuộc bất kỳ kiểu dữ liệu nào.

Schema Composition: Cho phép kết hợp nhiều schema để tạo các cấu trúc dữ liệu phức tạp.

Tùy chỉnh: Cho phép người dùng tùy chỉnh và điều chỉnh schema để đáp ứng các yêu cầu cụ thể và nhu cầu mô hình hóa dữ liệu.

Tham chiếu schema khác

Bạn có thể sử dụng tính năng "Tham chiếu schema khác" để tham chiếu các schema đã được định nghĩa trước đó.

Sau khi tham chiếu một schema khác, bạn có thể xem schema được tham chiếu trong Schema Editor.

Các điểm chính về schema được tham chiếu:

Mọi sửa đổi được thực hiện đối với schema gốc sẽ được phản ánh trong schema tham chiếu.

Không thể chỉnh sửa trực tiếp schema được tham chiếu; để thực hiện thay đổi, bạn có thể:

Nhấp vào tên schema để điều hướng đến schema gốc nhằm chỉnh sửa.

Bằng cách nhấp vào Dereference trên schema, schema sẽ chuyển đổi thành một loạt thuộc tính độc lập, cho phép bạn chỉnh sửa từng thuộc tính riêng lẻ.

Nếu bạn cần sửa đổi định nghĩa của một thuộc tính cụ thể một cách độc lập, bạn có thể chọn Dereference thuộc tính đó, cho phép sửa đổi riêng lẻ. Mọi thay đổi đối với schema gốc sẽ không ảnh hưởng đến thuộc tính đã được dereference.

Trong trường hợp không phải tất cả thuộc tính của schema được tham chiếu đều cần thiết trong endpoint, bạn có thể nhấp vào Hide để ẩn các thuộc tính không cần thiết.

Schema Composition

Nếu một thuộc tính trong cấu trúc dữ liệu của bạn có thể có nhiều kiểu dữ liệu khả dĩ, bạn có thể sử dụng Schema Composition để kết hợp nhiều schema.

Apidog hỗ trợ các từ khóa composition sau:

Từ khóa	Mô tả
allOf (AND)	Chỉ định rằng thuộc tính phải tuân theo tất cả schema được định nghĩa trong composition.
anyOf (OR)	Chỉ định rằng thuộc tính có thể tuân theo bất kỳ schema nào được liệt kê trong composition.
oneOf (XOR)	Chỉ định rằng thuộc tính phải tuân theo một và chỉ một trong các schema được định nghĩa trong composition.

Sau khi chọn Schema Composition, các thuộc tính con có tên "0" và "1" sẽ xuất hiện bên dưới thuộc tính, đại diện cho từng schema trong composition. Bạn có thể sửa đổi loại schema cho từng thuộc tính con và thêm các schema bổ sung nếu cần.

Trong tài liệu API, Schema Composition sẽ được hiển thị như sau:

Bạn sẽ thấy hai đối tượng tùy chọn bên dưới OneOf. Nếu bạn muốn hiển thị tên của chúng như trong hình, bạn cần nhập tên vào trường title trong Type editor.

Tùy chỉnh

Bằng cách chọn "Customize", bạn có thể chỉnh sửa trực tiếp JSON Schema trong trình chỉnh sửa.

Cài đặt thuộc tính

Đối với mỗi thuộc tính, có một số nút nằm bên cạnh kiểu dữ liệu:

Nút	Mô tả
*	Cho biết thuộc tính có bắt buộc hay không.
N	Chỉ định thuộc tính có cho phép giá trị null hay không.
Settings	Cho phép bạn chỉnh sửa các cài đặt nâng cao trong Type Editor.

Type Editor

Type Editor mô tả trực quan một thuộc tính phù hợp với JSON Schema.

Sau khi các cài đặt nâng cao này được cấu hình, chúng sẽ có hiệu lực trong các khu vực sau:

Khi thêm ví dụ phản hồi, bạn có thể nhấp để tự động tạo dựa trên các cài đặt.

Chúng sẽ được hiển thị trong tài liệu API.

Trong body của yêu cầu, bạn có thể nhấp để tự động tạo dựa trên các cài đặt.

Khi gửi một yêu cầu, dữ liệu được trả về sẽ được tự động xác thực theo các cài đặt.

Trong dịch vụ mock, dữ liệu phản hồi sẽ được tạo dựa trên các cài đặt.

Thuộc tính liệt kê

Đối với các kiểu String, Integer và Number, Apidog hỗ trợ enum. Bằng cách bật công tắc enum, bạn có thể thêm các giá trị enum và mô tả. Ngoài ra, bạn có thể thực hiện Bulk Edit cho các giá trị enum.

Mock

Ngoài các cài đặt nâng cao trong thuộc tính, bạn có thể chỉ định nội dung mock cho các trường bằng cách điền giá trị mock. Giá trị mock được ưu tiên hơn các cài đặt trong phần cài đặt nâng cao.

Giá trị mock hỗ trợ cú pháp Faker.js, cho phép bạn chọn dữ liệu faker mong muốn trực tiếp từ các tùy chọn thả xuống.

Giá trị mock cũng có thể được nhập dưới dạng giá trị cố định.

Cài đặt XML

Đối với dữ liệu XML, Type Editor trong Apidog cung cấp thêm Cài đặt XML. Bạn có thể bật công tắc XML, cấu hình các thuộc tính như tên thẻ, namespace, v.v., và xem trước cấu trúc XML tương ứng.

HashMap, Dictionary, Array

HashMap còn được gọi là Map, dictionary hoặc mảng kết hợp. Đây là một tập hợp các cặp khóa-giá trị, trong đó tên khóa có thể là bất kỳ nội dung nào, thay vì được định nghĩa trước.

Đặc tả OpenAPI hỗ trợ định nghĩa một HashMap với khóa dạng chuỗi. Điều này được thực hiện bằng cách đặt loại phần tử thành object, sau đó sử dụng từ khóa additionalProperties để chỉ định kiểu của các giá trị trong các cặp khóa-giá trị.

Giả sử có một API truy vấn thông tin người dùng và định dạng dữ liệu trả về có các yêu cầu sau:

Dữ liệu trả về là một đối tượng

Các phần tử con của đối tượng là các cặp khóa-giá trị của một HashMap

ID người dùng là khóa và thông tin người dùng là giá trị

Để định nghĩa điều này trong Apidog:

Tạo một schema mới và đặt tên là "UserProfiles".

Trong "UserProfiles", chỉ định nút gốc là kiểu "object". Sau đó nhấp vào Advanced Configuration, đặt additionalProperties thành Allow, và nhấp vào nút Settings ở bên phải.

Trong cửa sổ bật lên, thêm thông tin người dùng cần thiết, với tên và email của người dùng là các trường của đối tượng. Nội dung sẽ được lưu tự động.

Trong phần phản hồi của tài liệu API, tham chiếu schema tại nút gốc và chọn "user profiles" mà bạn vừa tạo.

Nhấp lưu, sau đó bạn có thể thấy schema đã định nghĩa và các giá trị ví dụ trong ví dụ phản hồi trả về trong tài liệu API.

Đối tượng có additionalProperties

Khi công việc phát triển thực tế được lặp lại, các đối tượng do API trả về có thể có additionalProperties so với đối tượng đã được định nghĩa ban đầu. Theo đặc tả OpenAPI, tình huống này cũng có thể được xử lý bằng tính năng "additionalProperties".

Giả sử hiện có một API truy vấn thông tin người dùng, trong đó các trường phản hồi được định nghĩa ban đầu khi truy vấn thông tin người dùng theo ID người dùng là name và email. Giờ đây, với việc nâng cấp hệ thống, bạn muốn bao gồm các trường khác.

Khi chỉnh sửa tài liệu API, bạn có thể định nghĩa như sau: Trong nút gốc của mô hình dữ liệu, nhấp vào Advanced Settings, đặt additionalProperties thành Allow, và đặt kiểu giá trị trường thành any.

Sau đó, bạn có thể thấy cấu trúc dữ liệu đã định nghĩa và các giá trị ví dụ trong tài liệu API.

Cấu trúc dữ liệu với additionalProperties

Tuples

Thông thường, các phần tử bên trong của một mảng phải có cùng kiểu, trong khi tuples có thể chứa các kiểu dữ liệu khác nhau. Nếu bạn muốn định nghĩa một tuple bao gồm cả kiểu string và integer, chẳng hạn như dữ liệu (0,"A",2,"C"), bạn có thể đặt loại phần tử thành array trong mô hình dữ liệu, sau đó đặt kiểu của items thành anyOf trong mẫu kết hợp, rồi thêm các phần tử con có kiểu string và integer tương ứng.

TIP

Nếu bạn muốn tạo nhiều phần tử khi tạo ví dụ, vui lòng chỉ định số lượng phần tử tối thiểu và tối đa trong cài đặt nâng cao của nút gốc.

Sau khi lưu, nhấp vào Generate Automatically trong tài liệu API để xem cấu trúc dữ liệu đã định nghĩa và các giá trị ví dụ.

Bạn cũng có thể xem các giá trị ví dụ của tuple trong phản hồi trả về trong tài liệu.

Công cụ

Schema Editor trong Apidog cung cấp một số công cụ rất hữu ích.

Công cụ	Mô tả
Generate from JSON etc.	Công cụ này cho phép bạn tự động tạo schema từ JSON, dữ liệu XML và các nguồn khác, hoặc trực tiếp từ cấu trúc bảng cơ sở dữ liệu. Tìm hiểu thêm về Tạo schema từ JSON, v.v..
Preview	Công cụ này tạo dữ liệu mock tuân theo định nghĩa schema, cung cấp bản xem trước của dữ liệu dự kiến.
Generate code	Công cụ này có thể tạo mã định nghĩa cấu trúc dữ liệu bằng nhiều ngôn ngữ lập trình khác nhau. Tìm hiểu thêm về Tạo mã.
JSON Schema	Công cụ này cho phép chỉnh sửa trực tiếp JSON schema để tinh chỉnh và tùy chỉnh.

FAQ

Q: Nếu một thuộc tính chuỗi có nhiều giá trị liệt kê và được sử dụng ở nhiều vị trí khác nhau, làm thế nào để enum này có thể được tham chiếu nhất quán trong toàn bộ tài liệu?

A: Bạn có thể định nghĩa thuộc tính này như một schema độc lập bao gồm một thuộc tính duy nhất, cho phép nó được tham chiếu nhất quán trên các phần khác nhau của tài liệu API.

Xây dựng Schema

Sử dụng Schema Editor#