Import OpenAPI Schema
Buka di CMSAlih-alih menambahkan API action satu per satu, Anda dapat mengimpor beberapa sekaligus dari definisi OpenAPI (Swagger) yang sudah ada. Dalam tutorial ini Anda mengimpor schema sampel Projects API milik Kirana ke Atlas, asisten operasional Kirana Group. Schema ini punya dua operation: get_project_status, yang sudah dimiliki Atlas dari Menghubungkan API Anda, dan list_projects, yang baru. Anda akan melihat bagaimana wizard import menambahkan API baru dan mengganti API yang sudah ada dengan nama yang sama.
Sebelum memulai
- Anda sudah mendaftarkan setidaknya satu API secara manual di Menghubungkan API Anda, sehingga Anda paham arti setiap field. Tutorial ini mengasumsikan
get_project_statusdari halaman tersebut sudah ada di halaman Custom API. - Anda memiliki spec OpenAPI 3.x untuk backend Anda, dalam bentuk file JSON atau YAML atau teks yang bisa ditempel. Untuk mengikuti tutorial ini, unduh schema sampel kirana-projects-openapi.json.
- Anda sudah tahu cara menguji dan mem-publish perubahan. Lihat Preview dan Publish Perubahan.
Kapan Menggunakan Fitur Ini
Gunakan Import OpenAPI schema ketika Anda sudah memiliki spec OpenAPI untuk backend Anda. Alih-alih mengisi nama, HTTP method, endpoint, dan parameter untuk setiap operation secara manual, qlar membaca spec dan membuat semua API action sekaligus.
Skenario umum:
- Anda mengekspor spec dari Postman, Swagger UI, atau API gateway Anda
- Tim backend Anda memelihara file OpenAPI sebagai bagian dari alur pengembangan
- Anda memindahkan banyak endpoint dari tool lain
Schema Sampel
kirana-projects-openapi.json mendeskripsikan API sampel publik yang hanya bisa dibaca, sama dengan yang dipakai di Menghubungkan API Anda. URL server-nya https://stpusakaappassetprod.blob.core.windows.net/docs-media/samples/kirana-api, dan ia punya dua operation:
operationId | Request | Yang dikembalikan |
|---|---|---|
get_project_status | GET /projects/{projectCode}.json | Status, progres, anggaran, dan tahap approval saat ini dari satu proyek |
list_projects | GET /projects/index.json | Kode, nama, dan status semua proyek Kirana yang aktif |
Langkah 1: Buka Wizard Import
Pada halaman Custom API, buka More actions, lalu klik Import OpenAPI schema. Panel samping Import OpenAPI schema terbuka. Stepper di bagian atas menampilkan empat langkah wizard: Upload, Edit, Review, dan Done. Panel terbuka di langkah Upload.
Langkah 2: Unggah Schema
Langkah Upload terdiri dari dua grup, Schema dan Authentication.
-
Schema format: pilih JSON atau YAML. Untuk sampel, pilih JSON. Anda harus memilih format dulu: editor di langkah berikutnya tetap nonaktif sampai Anda memilihnya.
-
Unggah file (opsional): area drop bertuliskan Drop a JSON or YAML file here dan punya tombol Choose file. Seret
kirana-projects-openapi.jsonke area drop, atau klik Choose file lalu pilih file. Setelah diunggah, nama dan ukuran file tampil dengan tombol Replace dan Remove. Remove juga mengosongkan teks schema. Saat Anda mengunggah file, qlar mengatur Schema format berdasarkan ekstensinya (.json,.yaml, atau.yml). Mengunggah file bersifat opsional: Anda juga bisa menempel schema di langkah berikutnya. -
Authentication: grup dengan satu pilihan, Authentication for the imported APIs:
- Keep what each API has now, or none for a new API (default): API baru diimpor tanpa authentication, dan API yang sudah ada tetap memakai authentication-nya.
- Use the same authentication for every imported API: field authentication muncul, dan setiap API hasil import mendapat authentication yang Anda isi di sini.
API sampel bersifat publik, jadi biarkan opsi pertama terpilih.

Klik Next. Jika belum memilih schema format, Next menampilkan error "Schema Format is required".
Langkah 3: Edit Schema
Langkah Edit menampilkan schema di editor OpenAPI schema. Jika Anda mengunggah file, isinya sudah ada di sana. Jika belum, tempel spec Anda ke editor sekarang. Anda masih bisa mengubah isinya di sini sebelum import, misalnya untuk memperbaiki sebuah deskripsi. Editor tetap kosong sampai Anda mengunggah file atau menempel schema, dan Next menampilkan "API Schema is required" selama editor masih kosong.

Klik Next. qlar mengonversi schema. Jika schema tidak bisa dibaca, dialog menampilkan "Couldn't convert the schema" beserta alasannya, dan Anda tetap di langkah ini. Untuk mengganti file atau format, klik Back.
Langkah 4: Tinjau Apa yang Akan Berubah
Langkah Review menampilkan What the import changes. Baris di bawah judul menghitung API, misalnya "1 new, 1 replaced", dan mengingatkan bahwa belum ada yang tersimpan sebelum Anda menyimpan halaman. Di bawahnya, tabel APIs in the schema mendaftar setiap API dengan kolom berikut:
- Change: New jika belum ada API di agent ini yang memakai nama itu, atau Replaced jika sudah ada. Nama dicocokkan meskipun huruf besar-kecil atau spasi di awal dan akhir berbeda.
- Name, Method, dan Endpoint.
Untuk sampel, list_projects berstatus New dan get_project_status berstatus Replaced.

Replaced APIs take the schema's fields: API yang di-replace mendapat description, method, endpoint, dan parameter dari schema. Rules, Response Prompt, dan Loading Text-nya tetap. Authentication-nya juga tetap, kecuali Anda memilih Use the same authentication for every imported API. Pada sampel,
get_project_statusmendapat deskripsi dari schema yang sedikit lebih pendek. Jika Anda lebih suka kalimat Anda sendiri, ubah setelah import.
Jika schema tidak punya API, tabel diganti dengan "The schema has no APIs to import." dan tombol import tetap nonaktif.
Klik Import 2 APIs. Tombol menampilkan jumlah API yang akan ditambahkan atau di-replace. Untuk mengubah sesuatu dulu, klik Back.
Langkah 5: Selesaikan Import
Langkah Done menampilkan Import complete dan pesan "Imported 2 APIs (1 new, 1 replaced). Check their authentication, then save the page to keep them." Tinggal satu tombol yang diklik: Close.

Klik Close. Daftar Custom API sekarang menampilkan get_project_status dan list_projects.
Langkah 6: Tinjau API Hasil Import
Klik setiap API hasil import untuk membuka panelnya, lalu periksa nama, deskripsi, HTTP method, endpoint, dan property-nya. API hasil import dimulai dengan Rules dan Response Prompt kosong, jadi tambahkan jika membantu. Untuk list_projects, misalnya:
- Rules:
List only projects that appear in the response. Do not add projects from memory. - Response Prompt:
Show one line per project: code, name and status.
Klik Apply untuk menyimpan perubahan Anda di form.
Langkah 7: Simpan Semua Perubahan
Import hanya mengubah form. Belum ada yang tersimpan. Klik Save all changes di bagian bawah halaman Custom API. CMS bertanya Are you sure to save your changes? Klik Yes. Sebuah pesan mengonfirmasi Custom APIs saved.
API action hasil import disimpan sebagai draft. Pengguna sungguhan baru mendapatkannya setelah Anda mengklik Publish di bar atas.
Catatan: Jika Anda meninggalkan halaman atau menutup browser sebelum Save all changes, API hasil import hilang dan Anda harus mengimpor ulang.
Apa yang Diimpor
| Field OpenAPI | Dipetakan ke field qlar |
|---|---|
operationId / summary | Action name |
description | Description |
method | HTTP Method |
servers[0].url + path | Target URI |
parameters | Properties (path, query) |
requestBody | Properties (body) |
Catatan: Import mencakup field OpenAPI 3.x yang paling umum. Beberapa konstruksi lanjutan (misalnya schema
allOf/oneOfyang kompleks atau parameter upload file) mungkin tidak terpetakan sepenuhnya dan perlu disesuaikan manual setelah import.
Periksa hasilnya
-
Tes sebuah action. Klik
list_projects, lalu Test API, dan klik Call API. Anda seharusnya mendapat200 OKdan daftar berisi KG-2041, KG-2052, dan KG-2063. -
Coba dalam percakapan. Pada panel preview, klik tombol reload lalu tanyakan:
Which projects are active right now?Atlas seharusnya memanggil
list_projectsdan menampilkan tiga proyek sampel beserta statusnya. Lalu tanyakan "What is the status of KG-2052?" untuk memastikanget_project_statusyang diperbarui masih berfungsi. -
Perjelas deskripsi. AI menggunakan nama dan deskripsi action untuk memutuskan kapan memanggil setiap API. Jika deskripsi hasil import kosong atau terlalu umum, buat lebih spesifik.
Langkah berikutnya
- Berikutnya dalam alur: Mengatur Autentikasi, untuk menerapkan credential ke semua API hasil import sekaligus.
- Menghubungkan API Anda: daftarkan satu API action secara manual dan pahami semua opsi yang tersedia.
- Using Plugins: gunakan integrasi siap pakai alih-alih mengonfigurasi API mentah.