Import OpenAPI Schema

Buka di CMS

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 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_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:

operationIdRequestYang dikembalikan
get_project_statusGET /projects/{projectCode}.jsonStatus, progres, anggaran, dan tahap approval saat ini dari satu proyek
list_projectsGET /projects/index.jsonKode, 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.

  1. Schema format: pilih JSON atau YAML. Untuk sampel, pilih JSON. Anda harus memilih format dulu: editor di langkah berikutnya tetap nonaktif sampai Anda memilihnya.

  2. Unggah file (opsional): area drop bertuliskan Drop a JSON or YAML file here dan punya tombol Choose file. Seret kirana-projects-openapi.json ke 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.

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

Drawer Import OpenAPI schema pada langkah Upload (langkah 1 dari 4) dengan file kirana-projects-openapi.json beserta Replace dan Remove, Schema format JSON dipilih, dan Authentication for the imported APIs diatur ke Keep what each API has now, or none for a new API

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.

Langkah Edit (langkah 2 dari 4) dengan editor OpenAPI schema yang menampilkan JSON Kirana Projects API (sample): openapi 3.0.3, blok info, URL servers https://app-asset.qlar.ai/docs-media/samples/kirana-api dan awal path /projects/{projectCode}.json dengan operationId get_project_status, serta tombol Back dan Next

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.

Langkah Review (langkah 3 dari 4) dengan What the import changes, pemberitahuan Replaced APIs take the schema fields, dan tabel dengan list_projects bertanda New dan get_project_status bertanda Replaced, masing-masing dengan Method GET dan endpoint-nya, serta tombol Back dan Import 2 APIs

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_status mendapat 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.

Langkah Done (langkah 4 dari 4) dengan tanda centang hijau, Import complete, pesan Imported 2 APIs (1 new, 1 replaced). Check their authentication, then save the page to keep them., dan tombol 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 OpenAPIDipetakan ke field qlar
operationId / summaryAction name
descriptionDescription
methodHTTP Method
servers[0].url + pathTarget URI
parametersProperties (path, query)
requestBodyProperties (body)

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.