Import OpenAPI Schema

Alih-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 memperbarui API yang sudah ada.

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_status dari 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:

Langkah 1: Buka Wizard Import

Pada halaman Custom API, klik Import OpenAPI Schema. Jendela Import OpenAPI Schema terbuka. Stepper di bagian atas menunjukkan empat langkah wizard: Schema Setup, Preview, Confirmation, dan Result.

Langkah 2: Siapkan Schema

Langkah Schema Setup terdiri dari tiga bagian:

1. Schema Format: pilih JSON atau YAML. Untuk sampel, pilih JSON.

2. Upload a JSON / YAML file to fill the editor automatically. Seret kirana-projects-openapi.json ke area drop, atau klik area tersebut lalu pilih file. Nama file muncul dengan tulisan Click to change file di bawahnya. 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.

3. Override Authentication:

   • No — use existing / no authentication (default): API baru diimpor tanpa authentication, dan API yang sudah ada tetap memakai authentication-nya.
   • Yes — apply custom authentication to all imported APIs: field authentication muncul, dan setiap API hasil import mendapat authentication yang Anda isi di sini.

   API sampel bersifat publik, jadi biarkan No terpilih.

Klik Next.

Langkah 3: Periksa Schema di Editor

Langkah Preview menampilkan schema di editor Paste your OpenAPI schema here. 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.

Klik Next. qlar mengonversi schema. Jika schema tidak bisa dibaca, pesan error menjelaskan penyebabnya dan Anda tetap di langkah ini.

Langkah 4: Tinjau Apa yang Akan Berubah

Langkah Confirmation menampilkan Import Preview dengan dua daftar:

• New APIs: operation yang namanya belum ada di agent ini. Untuk sampel: list_projects.
• Updated APIs: operation yang namanya sama dengan API yang sudah Anda miliki. Untuk sampel: get_project_status.

Arti "updated": untuk API yang sudah ada, Description, HTTP Method, Target URI, dan property dari schema menggantikan yang lama. Rules, Response Prompt, Loading Text, dan authentication-nya (kecuali Anda memilih override) tetap seperti semula. Pada sampel, get_project_status mendapat deskripsi dari schema yang sedikit lebih pendek. Jika Anda lebih suka kalimat Anda sendiri, ubah setelah import.

Klik Start Import.

Langkah 5: Tutup Hasilnya

Langkah Result mengonfirmasi Import Successful dengan Successfully imported 2 APIs (1 new, 1 updated). serta pengingat: "You may need to configure authentication before these APIs can be used. Please review your tools and save to apply changes."

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 Update API 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 API successfully updated!

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

Catatan: Import mencakup field OpenAPI 3.x yang paling umum. Beberapa konstruksi lanjutan (misalnya schema allOf/oneOf yang kompleks atau parameter upload file) mungkin tidak terpetakan sepenuhnya dan perlu disesuaikan manual setelah import.

Periksa hasilnya

1. Tes sebuah action. Klik list_projects, lalu Test API, dan klik Call API. Anda seharusnya mendapat 200 OK dan daftar berisi KG-2041, KG-2052, dan KG-2063.

2. Coba dalam percakapan. Pada panel preview, klik tombol reload lalu tanyakan:

   Which projects are active right now?
   

   Atlas seharusnya memanggil list_projects dan menampilkan tiga proyek sampel beserta statusnya. Lalu tanyakan "What is the status of KG-2052?" untuk memastikan get_project_status yang diperbarui masih berfungsi.

3. 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.