Mengakses dan memperbarui dokumentasi sebuah API yang diimpor

Ketika Anda mengimpor sebuah spesifikasi, Restorm tidak hanya membuat permintaan: ia juga menyimpan dokumentasi API-nya — deskripsi, model, skema keamanan, contoh, enumerasi — dan melampirkannya ke folder variabel yang dibuat oleh impornya.

Mengakses dokumentasinya

Tab Docs pada folder variabel

Inilah tampilan utamanya. Bukalah folder variabel hasil impornya: bilah sub-tabnya memuat sebuah tab Docs, di samping Lingkungan, Variabel kustom, dan Catatan.

Tab itu hanya muncul jika foldernya berasal dari sebuah impor — folder variabel yang Anda buat secara manual tidak punya dokumentasi untuk ditampilkan.

Jalur akses lainnya

Dari	Yang Anda peroleh
Tab Docs sebuah permintaan	Dokumentasi operasi itu saja — tanpa daftar isi maupun blok informasi umum. Tab ini hanya muncul jika operasinya ditemukan di dalam spesifikasinya
Tab Docs sebuah folder biasa	Dokumentasi yang dibatasi pada operasi yang dimuat folder tersebut
Sub-tab beranda folder variabel	Kartu Lihat dokumentasi — “Telusuri dokumentasi API, model, dan endpoint-nya”
Layar sambutan (kartu API)	Tautan cepat Dokumentasi
Mesin pencarian di bilah judul	Pratinjau dokumentasi saat kursor diarahkan ke sebuah hasil

Apa yang dimuat tampilannya

Dari atas ke bawah:

• judul API beserta deskripsinya;
• sebuah blok informasi: Version, Source format (dengan tautan ke URL sumbernya), Server (skema, host, jalur dasar), Contact, License, Terms of service, External docs;
• sebuah bagian per label, beserta deskripsinya;
• sebuah blok per operasi: metode dan URL, ringkasan, titik penanda grup, lencana deprecated bila ada, bagian Security (tipe skema, alur OAuth 2, cakupan), dan sebuah Example payload yang dapat dilipat;
• tabel Parameters dan Responses (kode statusnya diberi warna);
• Models — sebuah graf interaktif berisi skemanya, yang dapat dinavigasi dan diperbesar;
• Polymorphism — komposisi oneOf / anyOf / allOf;
• Enums — enumerasinya, digabungkan dengan enumerasi milik foldernya.

Note

Judul bagian-bagian tersebut (Models, Enums, Parameters, Responses, Security, Example payload) ditampilkan dalam bahasa Inggris pada semua bahasa aplikasi. Judul itu dikutip apa adanya di sini agar Anda menemukannya kembali di layar.

Membuat permintaan dari dokumentasinya

Setiap blok operasi memiliki tombol + Add yang membuat sebuah permintaan yang sudah terkonfigurasi untuk operasi tersebut. Inilah jalan terpendek ketika sebuah impor hanya sebagian, atau ketika sebuah operasi baru saja muncul di dalam spesifikasinya.

Bernavigasi dan mencari

Sebuah daftar isi ditambatkan di sebelah kanan — bagian Overview, Operations, Models, Enums — dapat dilipat dan diubah ukurannya. Mengklik sebuah model akan menggulir hingga ke grafnya dan memusatkan node yang bersesuaian di sana.

Pintasan	Efek
Ctrl+F / Cmd+F	Membuka pencarian di dalam dokumentasinya
F3 / Enter	Kecocokan berikutnya
Shift+F3 / Shift+Enter	Kecocokan sebelumnya
Esc	Menutup pencariannya

Sebuah penghitung menunjukkan posisi Anda di antara hasilnya.

Memperbarui dokumentasinya

Sebuah spesifikasi berubah. Restorm mampu mengambil kembali sumbernya dan menerapkan deltanya — dokumentasi dan permintaan — tanpa menimpa pekerjaan Anda.

Hanya untuk impor lewat URL

Sinkronisasi ulang hanya tersedia jika foldernya diimpor dari sebuah URL. Impor dari file atau lewat penempelan tidak menyimpan sumber, dan tombol penyegarannya tidak muncul: sub-tab berandanya menampilkan “Folder ini tidak dibuat dari sumber yang dapat diimpor.”

URL tersebut tidak dapat diubah setelahnya dari antarmuka. Untuk mengganti sumbernya, lakukan impor ulang.

Di mana letak tombolnya

Dua jalan masuk, yang setara:

1. sub-tab beranda folder variabel, bagian Pembaruan spesifikasi — yang menampilkan URL, Impor terakhir, dan Pemeriksaan terakhir, serta memuat tombol Segarkan;
2. klik kanan pada foldernya di pohon samping → Segarkan.

Tidak ada pemeriksaan otomatis

Restorm tidak memantau spesifikasi Anda di latar belakang dan tidak akan memberi tahu Anda bahwa versi baru telah tersedia. Pemeriksaannya selalu Anda sendiri yang memicu.

Apa yang terjadi

1. Sebuah jendela “Menyegarkan spesifikasi…” muncul selama pengambilannya. {{variabel}} pada URL dan headernya diselesaikan, dan rute autentikasi yang terlampir dijalankan lebih dahulu.
2. Restorm membandingkan sebuah sidik jari sumber yang diambil dengan sidik jari yang disimpan pada impor terakhir.
3. Tidak ada yang berubah → “Spesifikasi API sudah mutakhir.”, dan selesai.
4. Ada yang berubah (atau pengambilannya gagal) → asisten sinkronisasi ulang terbuka.

Asistennya

• URL sumber ditampilkan sebagai baca-saja.
• Sebuah tombol memungkinkan Anda melampirkan, mengubah, atau melepaskan rute autentikasi, dan submenu Custom headers memungkinkan penambahan header tetap yang dimainkan ulang pada setiap penyegaran.
• Dua tab pratinjau:
  • Routes — pohon operasi yang ditemukan di versi barunya, lengkap dengan filter dan pemilihan. Operasi yang sudah ada di folder Anda terkunci dan selalu tercentang; Anda hanya memilih operasi baru mana yang akan ditambahkan;
  • Documentation — dokumentasi versi barunya, baca-saja, sebelum Anda mengonfirmasi.
• Tombol konfirmasinya menampilkan jumlah operasi baru yang dipilih, misalnya Apply update (3).

Note

Asistennya saat ini ditampilkan dalam bahasa Inggris apa pun bahasa aplikasinya (“Refresh from source”, “Apply update”, tab “Routes” dan “Documentation”). Karena itu judul berbahasa Inggrisnya dikutip apa adanya di sini.

Apa yang diubah, dan apa yang tidak

Inilah butir pentingnya: spesifikasi berwenang atas apa yang digambarkannya, Anda berwenang atas selebihnya.

Elemen	Perilaku
Nama sebuah permintaan	Tidak pernah diubah
Metode dan URL	Tidak pernah diubah
Parameter, header, dan parameter jalur yang sudah ada	Dipertahankan apa adanya — nilai, deskripsi, pengaktifannya
Parameter yang ditambahkan oleh spesifikasinya	Ditambahkan, dengan nilai bawaan dari spesifikasinya atau dikosongkan
Parameter yang dihapus dari spesifikasinya	Dipertahankan pada permintaannya
Operasi baru	Ditambahkan di tempat yang akan dipilih oleh impor baru (termasuk folder labelnya)
Operasi yang ditandai usang oleh spesifikasinya	Dilaporkan; ia tampak meredup di dalam pohon
Operasi yang hilang dari spesifikasinya	Dilaporkan sebagai dihapus; ia tampak dicoret di dalam pohon, tetap dapat dieksekusi, dan tidak pernah dihapus
Dokumentasi API dan enumerasi	Diganti sepenuhnya oleh versi barunya — inilah yang menyegarkan tab Docs

Tidak pernah ada yang dihapus dari pohon Anda: sebuah operasi yang hilang dari sumbernya hanya ditandai, tidak dihapus.

Jika sumbernya meminta autentikasi

Respons 401 atau 403 akan membuka asistennya dengan pesan galat yang ditampilkan apa adanya (misalnya HTTP 401: Unauthorized). Lampirkan sebuah rute autentikasi atau tambahkan header tetap, lalu pratinjaunya dijalankan ulang.

Format yang dapat disinkronkan ulang

Dua belas format memiliki sinkronisasi ulang: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC, dan Smithy.

Untuk semua format lainnya, sebuah impor baru akan membuat pohon baru. Daftar lengkapnya ada di Memperbarui dari sumber.