Membangun Schema

Memanfaatkan Schema Editor

Schema Editor adalah alat yang andal yang membantu dalam merancang dan memodelkan struktur data yang digunakan oleh API Anda. Alat ini didasarkan pada JSON Schema dan digunakan untuk merancang struktur data JSON atau XML.

Gunakan Schema Editor untuk:

Mengembangkan body permintaan dan respons API yang disesuaikan untuk endpoint API tertentu.

Membangun model data yang dapat diterapkan di satu atau beberapa API.

Setiap schema dimulai dengan objek root. Untuk membangun schema, tambahkan properti ke objek root ini.

Tambahkan Properti

Klik tanda + (Tambahkan node turunan) di sebelah objek root untuk memperkenalkan properti baru.

Beri Nama Properti Anda

Masukkan nama (atau key) untuk properti tersebut.

Pilih Tipe Properti

Pilih tipe data umum atau pilih referensi ke schema yang telah ditentukan sebelumnya.

Pengaturan Lanjutan

Gunakan Type Editor untuk menetapkan tipe data, seperti nilai default dan format, untuk setiap properti.

Kelola Properti

Susun ulang properti dengan memindahkan, menyalin, atau menghapusnya. Anda juga dapat memperkaya properti dengan deskripsi dan menandainya sebagai wajib.

Metode Alternatif

Anda juga dapat membuat schema baru dengan mengimpor dari tabel database atau file JSON schema. Pelajari selengkapnya tentang Generate Schemas from JSON etc..

Tipe Properti

Selaras dengan standar JSON Schema, Apidog Schema Editor mendukung tipe data dasar berikut:

Tipe	Deskripsi
null	Merepresentasikan nilai JSON "null".
boolean	Merepresentasikan nilai "true" atau "false", yang sesuai dengan nilai JSON "true" atau "false".
object	Merepresentasikan kumpulan pasangan key-value yang tidak berurutan, yang sesuai dengan nilai JSON "object".
array	Merepresentasikan daftar nilai yang berurutan, yang sesuai dengan nilai JSON "array".
number	Merepresentasikan nilai angka desimal basis-10 dengan presisi arbitrer, yang sesuai dengan nilai JSON "number".
string	Merepresentasikan string karakter Unicode, yang sesuai dengan nilai JSON "string".

Tipe Data Array

Saat menggunakan tipe data array, properti sub-level ITEMS akan dibuat secara otomatis. Properti ini menentukan tipe data elemen di dalam array.

Selain struktur data standar yang disebutkan sebelumnya, Apidog Schema Editor juga mendukung hal berikut:

Mereferensikan schema lain: Kemampuan untuk mereferensikan dan menggunakan kembali schema yang didefinisikan di tempat lain dalam dokumentasi API.

any: Merepresentasikan nilai yang dapat berupa tipe data apa pun.

Komposisi Schema: Memungkinkan penggabungan beberapa schema untuk membuat struktur data yang kompleks.

Kustomisasi: Memungkinkan pengguna menyesuaikan dan mengadaptasi schema agar memenuhi persyaratan spesifik serta kebutuhan pemodelan data.

Mereferensikan Schema Lain

Anda dapat menggunakan fitur "Reference other schemas" untuk mereferensikan schema yang telah didefinisikan sebelumnya.

Setelah mereferensikan schema lain, Anda dapat melihat schema yang direferensikan di Schema Editor.

Poin penting tentang schema yang direferensikan:

Setiap modifikasi yang dilakukan pada schema asli akan tercermin dalam schema yang mereferensikannya.

Schema yang direferensikan tidak dapat diedit secara langsung; untuk melakukan perubahan, Anda dapat:

Mengklik nama schema untuk menavigasi ke schema asli dan mengeditnya.

Dengan mengklik Dereference pada schema, schema tersebut akan berubah menjadi serangkaian properti independen, sehingga Anda dapat mengeditnya satu per satu.

Jika Anda perlu memodifikasi definisi properti tertentu secara independen, Anda dapat memilih untuk melakukan Dereference pada properti tersebut, sehingga memungkinkan modifikasi individual. Perubahan apa pun pada schema asli tidak akan memengaruhi properti yang telah di-dereference.

Dalam kasus ketika tidak semua properti dari schema yang direferensikan diperlukan di endpoint, Anda dapat mengklik Hide untuk menyembunyikan properti yang tidak diperlukan.

Komposisi Schema

Jika suatu properti dalam struktur data Anda dapat memiliki beberapa kemungkinan tipe data, Anda dapat menggunakan Komposisi Schema untuk menggabungkan beberapa schema.

Apidog mendukung keyword komposisi berikut:

Keyword	Deskripsi
allOf (AND)	Menentukan bahwa properti harus mematuhi semua schema yang didefinisikan dalam komposisi.
anyOf (OR)	Menentukan bahwa properti dapat sesuai dengan salah satu schema yang tercantum dalam komposisi.
oneOf (XOR)	Menentukan bahwa properti harus mematuhi satu dan hanya satu dari schema yang didefinisikan dalam komposisi.

Setelah memilih Komposisi Schema, sub-properti bernama "0" dan "1" akan muncul di bawah properti, yang merepresentasikan setiap schema dalam komposisi. Anda dapat memodifikasi tipe schema untuk setiap sub-properti dan menambahkan schema tambahan sesuai kebutuhan.

Dalam dokumentasi API, Komposisi Schema akan ditampilkan seperti ini:

Anda akan melihat dua objek opsional di bawah OneOf. Jika Anda ingin menampilkan namanya seperti yang ditunjukkan pada gambar, Anda perlu memasukkan nama tersebut di bidang title dalam Type Editor.

Kustomisasi

Dengan memilih "Customize," Anda dapat mengedit JSON Schema secara langsung di dalam editor.

Pengaturan Properti

Untuk setiap properti, terdapat beberapa tombol yang terletak di sebelah tipe data:

Tombol	Deskripsi
*	Menunjukkan apakah properti tersebut wajib.
N	Menentukan apakah properti mengizinkan nilai null.
Settings	Memungkinkan Anda mengedit pengaturan lanjutan di Type Editor.

Type Editor

Type Editor mendeskripsikan properti secara visual selaras dengan JSON Schema.

Setelah pengaturan lanjutan ini dikonfigurasi, pengaturan tersebut akan berlaku di area berikut:

Saat menambahkan contoh respons, Anda dapat mengklik untuk membuatnya secara otomatis berdasarkan pengaturan.

Pengaturan tersebut akan ditampilkan dalam dokumentasi API.

Dalam body permintaan, Anda dapat mengklik untuk membuatnya secara otomatis berdasarkan pengaturan.

Saat mengirim permintaan, data yang dikembalikan akan divalidasi secara otomatis terhadap pengaturan tersebut.

Dalam layanan mock, data respons akan dibuat berdasarkan pengaturan tersebut.

Properti Enumerasi

Untuk tipe String, Integer, dan Number, Apidog mendukung enum. Dengan mengaktifkan sakelar enum, Anda dapat menambahkan nilai enum dan deskripsi. Selain itu, Anda dapat melakukan Bulk Edit untuk nilai enum.

Mock

Selain pengaturan lanjutan pada properti, Anda dapat menentukan konten mock untuk bidang dengan mengisi nilai mock. Nilai mock memiliki prioritas atas pengaturan dalam pengaturan lanjutan.

Nilai mock mendukung sintaks Faker.js, sehingga Anda dapat memilih data faker yang diinginkan secara langsung dari opsi dropdown.

Nilai mock juga dapat dimasukkan sebagai nilai tetap.

Pengaturan XML

Untuk data XML, Type Editor di Apidog menawarkan Pengaturan XML tambahan. Anda dapat mengaktifkan sakelar XML, mengonfigurasi properti seperti nama tag, namespace, dan sebagainya, serta melihat pratinjau struktur XML yang sesuai.

HashMap, Dictionary, Array

HashMap, juga dikenal sebagai Map, dictionary, atau associative array. Ini adalah kumpulan pasangan key-value, di mana nama key dapat berupa konten apa pun, bukan yang telah ditentukan sebelumnya.

Spesifikasi OpenAPI mendukung pendefinisian HashMap dengan key string. Hal ini dilakukan dengan menetapkan tipe elemen ke object, lalu menggunakan keyword additionalProperties untuk menentukan tipe nilai dalam pasangan key-value.

Misalkan terdapat API kueri informasi pengguna, dan format data yang dikembalikan memiliki persyaratan berikut:

Data yang dikembalikan adalah sebuah objek

Elemen turunan dari objek tersebut adalah pasangan key-value dari sebuah HashMap

ID pengguna adalah key, dan informasi pengguna adalah nilainya

Untuk mendefinisikan ini di Apidog:

Buat schema baru dan beri nama "UserProfiles".

Di "UserProfiles", tentukan node root sebagai tipe "object". Kemudian klik Advanced Configuration, atur additionalProperties ke Allow, dan klik tombol Settings di sebelah kanan.

Dalam pop-up, tambahkan informasi pengguna yang diperlukan, dengan nama dan email pengguna sebagai bidang objek. Informasi ini disimpan secara otomatis.

Dalam respons dokumentasi API, referensikan schema pada node root dan pilih "user profiles" yang baru saja Anda buat.

Klik simpan, lalu Anda dapat melihat schema yang telah didefinisikan dan nilai contoh dalam contoh respons pengembalian di dalam dokumentasi API.

Objek dengan additionalProperties

Seiring iterasi pekerjaan pengembangan aktual, objek yang dikembalikan oleh API mungkin memiliki additionalProperties dibandingkan dengan objek yang awalnya didefinisikan. Menurut spesifikasi OpenAPI, situasi ini juga dapat ditangani menggunakan fitur "additionalProperties".

Misalkan sekarang terdapat API kueri informasi pengguna, di mana bidang respons yang awalnya didefinisikan saat mengueri informasi pengguna berdasarkan ID pengguna adalah name dan email. Sekarang, dengan peningkatan sistem, Anda ingin menyertakan bidang lain.

Saat mengedit dokumentasi API, Anda dapat mendefinisikannya sebagai berikut: Pada node root model data, klik Advanced Settings, atur additionalProperties ke Allow, dan atur tipe nilai bidang ke any.

Kemudian Anda dapat melihat struktur data yang telah didefinisikan dan nilai contoh dalam dokumentasi API.

Struktur data dengan additionalProperties

Tuple

Biasanya, elemen internal dari sebuah array harus bertipe sama, sedangkan tuple dapat berisi tipe data yang berbeda. Jika Anda ingin mendefinisikan tuple yang mencakup tipe string dan integer, seperti data (0,"A",2,"C"), Anda dapat menetapkan tipe elemen ke array dalam model data, kemudian menetapkan tipe items ke anyOf dalam pola kombinasi, lalu menambahkan elemen turunan bertipe string dan integer masing-masing.

TIP

Jika Anda ingin menghasilkan beberapa elemen saat membuat contoh, harap tentukan jumlah minimum dan maksimum elemen dalam pengaturan lanjutan node root.

Setelah menyimpan, klik Generate Automatically dalam dokumentasi API untuk melihat struktur data yang telah didefinisikan dan nilai contoh.

Anda juga dapat melihat nilai contoh tuple dalam respons pengembalian di dokumentasi.

Alat

Schema Editor di Apidog menyediakan beberapa alat yang sangat berguna.

Alat	Deskripsi
Generate from JSON etc.	Alat ini memungkinkan Anda membuat schema secara otomatis dari JSON, data XML, dan sumber lain, atau langsung dari struktur tabel database. Pelajari selengkapnya tentang Generate schemas from JSON etc..
Preview	Alat ini membuat data mock yang mematuhi definisi schema, sehingga memberikan pratinjau data yang diharapkan.
Generate code	Alat ini dapat menghasilkan kode definisi struktur data dalam berbagai bahasa pemrograman. Pelajari selengkapnya tentang Generate code.
JSON Schema	Alat ini memungkinkan pengeditan langsung JSON schema untuk penyempurnaan dan kustomisasi.

FAQ

T: Jika properti string memiliki beberapa nilai enumerasi dan digunakan di berbagai lokasi, bagaimana enum ini dapat direferensikan secara konsisten di seluruh bagian?

J: Anda dapat mendefinisikan properti ini sebagai schema mandiri yang terdiri dari satu properti, sehingga memungkinkannya direferensikan secara konsisten di berbagai bagian dokumentasi API.

Membangun Schema

Memanfaatkan Schema Editor#