Saat Anda membuka dokumen API online yang diterbitkan menggunakan Apidog, Anda akan melihat tombol "Coba" di samping setiap *endpoint*. Mengkliknya akan memunculkan panel *debug* di sisi kanan halaman, memungkinkan Anda menguji API langsung dalam dokumentasi.
Namun, kegunaan fitur "Debug" ini sangat bergantung pada seberapa baik Anda mengonfigurasinya di dalam platform. Faktor-faktor seperti pengaturan URL yang tepat, konfigurasi autentikasi, struktur parameter yang jelas, dan data contoh yang lengkap secara signifikan memengaruhi pengalaman *debugging*.
Jika tidak dikonfigurasi dengan benar, pengguna mungkin menghabiskan banyak waktu untuk mengisi parameter atau bahkan gagal melakukan panggilan API yang berhasil, yang jauh dari ideal.
Mari kita bahas cara mengonfigurasi Apidog secara efektif untuk memastikan dokumentasi online yang diterbitkan memberikan pengalaman *debugging* yang luar biasa.
Konfigurasi URL yang Tepat
Seringkali, dokumentasi online terlihat baik-baik saja tetapi gagal saat Anda mengklik tombol "Coba" untuk mengirim permintaan. Alasan paling umum adalah *endpoint* hanya menyertakan jalur seperti /pet/{petId} tanpa memilih lingkungan *runtime* selama publikasi.
Ini menghasilkan URL permintaan yang tidak lengkap tanpa protokol atau nama *host*, menyebabkan kesalahan saat mengirim permintaan.
Untuk mengatasi hal ini, pastikan pengguna dapat mengakses URL yang benar. Apidog menawarkan tiga cara untuk mengonfigurasi URL untuk dokumentasi online, tergantung pada kebutuhan Anda.
1. Gunakan URL Dasar
Ini adalah pendekatan yang direkomendasikan. Tentukan hanya jalur di *endpoint*, seperti /pet/{petId}, dan konfigurasikan alamat layanan lengkap (misalnya, https://product.example.com) di bagian "Manajemen Lingkungan" sebagai URL Dasar.
Saat menerbitkan dokumentasi API, pilih lingkungan *runtime* yang sesuai. Apidog akan secara otomatis menggabungkan URL Dasar dengan jalur *endpoint*. Anda juga dapat menentukan beberapa lingkungan *runtime*, masing-masing dengan URL Dasar sendiri.
Dalam dokumentasi online, pengguna dapat dengan cepat beralih lingkungan dari daftar *dropdown*, dan semua URL *endpoint* akan diperbarui sesuai. Ini memudahkan validasi API di lingkungan yang berbeda.
Catatan: Perhatikan masalah protokol. Banyak peramban membatasi halaman HTTPS untuk memanggil API HTTP. Jika API Anda menggunakan HTTP, pengguna mungkin mengalami masalah lintas protokol saat melakukan *debug* di halaman dokumentasi HTTPS.
2. Sertakan URL Lengkap di Endpoint
Pilihan lain adalah menentukan URL lengkap langsung di *endpoint*, seperti https://product.example.com/pet/{petId}.
Ini memastikan URL permintaan lengkap terlihat terlepas dari lingkungan *runtime* yang dipilih. Namun, mengelola perubahan alamat server menjadi rumit karena Anda perlu memperbarui setiap *endpoint* secara individual. Oleh karena itu, metode ini kurang direkomendasikan.
3. Gunakan Variabel dalam URL
Jika Anda ingin pengguna menyesuaikan URL untuk *debugging*, Anda dapat menggunakan variabel. Misalnya, buat variabel lingkungan BaseURL di bagian "Manajemen Lingkungan" dan referensikan di URL Dasar sebagai {{BaseURL}}.
Dalam dokumentasi online, pengguna dapat mengklik nama variabel dan memodifikasinya ke URL yang mereka inginkan.
Atau, Anda dapat menentukan variabel langsung di *endpoint*, seperti {{BaseURL}}/pet/{petId}.
Untuk *endpoint* spesifik tersebut dalam dokumentasi online, pengguna dapat mengatur nilai variabel untuk mengirim permintaan.
Sebelum menerbitkan dokumentasi, pastikan "nilai awal" di lingkungan tidak mengandung informasi sensitif (misalnya, kredensial autentikasi), karena nilai-nilai ini akan disertakan dalam dokumentasi yang diterbitkan dan dapat menimbulkan risiko privasi.
Konfigurasi Autentikasi yang Tepat
Pengaturan Autentikasi Dasar
Permintaan *endpoint* yang berhasil seringkali memerlukan autentikasi. Apidog mendukung berbagai jenis autentikasi, termasuk Bearer Token, API Key, OAuth2.0, dan Basic Auth.
Anda dapat mengonfigurasi autentikasi pada tingkat *endpoint* atau folder menggunakan skema keamanan atau dengan mengaturnya secara manual.
Misalnya, saat menggunakan Bearer Token sebagai jenis autentikasi, bidang "Token" muncul di bagian atas panel *debug* dalam dokumentasi online. Pengguna dapat memasukkan nilai token langsung tanpa secara manual menambahkan awalan "Bearer". Apidog menangani ini secara otomatis, membuatnya lebih nyaman daripada menambahkan *header* otorisasi secara manual.
Keuntungan dari pengaturan ini adalah informasi autentikasi dapat dibagikan di beberapa *endpoint*. Jika beberapa *endpoint* menggunakan skema atau jenis keamanan yang sama, Anda hanya perlu memasukkan kredensial sekali. Setiap pembaruan kredensial akan secara otomatis berlaku untuk semua *endpoint* terkait.
Kredensial autentikasi dienkripsi dan disimpan secara lokal di peramban pengguna, dikelola per sesi, dan dibagikan di seluruh tab dan jendela. Kredensial tersebut dihapus saat peramban ditutup, mengurangi risiko terpaparnya informasi sensitif dalam dokumentasi yang diterbitkan.
Konfigurasi OAuth2.0
Untuk autentikasi OAuth2.0, jika Anda ingin pengguna menghasilkan token langsung selama *debugging*, konfigurasikan detail server otorisasi (misalnya, URL Autentikasi, URL Token) dalam proyek.
Saat menggunakan skema keamanan OAuth2.0, pengguna perlu memasukkan ID klien, rahasia klien, dll., selama *debugging*. Sebuah *pop-up* akan memandu mereka melalui proses otorisasi, dan access_token yang diperoleh akan secara otomatis diterapkan ke permintaan API berikutnya.
Rancang Struktur Parameter yang Jelas
Tampilan Parameter di Panel Debug
Panel *debug* secara cerdas menampilkan bagian parameter berdasarkan desain *endpoint* Anda. Misalnya, jika *endpoint* hanya mendefinisikan parameter Jalur, panel *debug* hanya akan menampilkan bagian Jalur, menghindari bagian Kueri atau Badan yang tidak perlu.
Kejelasan ini membantu pengguna memahami parameter mana yang harus diisi tanpa terganggu oleh bagian yang tidak relevan.
Berikan Contoh
Saat merancang *endpoint*, definisikan jenis dan atribut yang diperlukan setiap parameter secara akurat. Sertakan deskripsi dan contoh yang jelas, karena ini akan diisi sebelumnya di panel *debug*, meningkatkan kegunaan.
Hindari Header yang Berlebihan
Jika *endpoint* mendefinisikan parameter Badan, tidak perlu secara manual menambahkan *header* seperti Content-Type: application/json. Apidog secara otomatis menangani *header* tersebut selama permintaan.
Demikian pula, jika autentikasi dikonfigurasi, hindari duplikasi di *header*. Pengaturan autentikasi diutamakan dan akan menimpa konfigurasi *header* yang bertentangan.
Tawarkan Contoh Permintaan Komprehensif
Untuk *endpoint* dengan badan permintaan JSON yang kompleks, berikan beberapa contoh badan permintaan selama desain.
Pengguna dapat memilih contoh-contoh ini dari menu *dropdown* di panel *debug*, menghemat waktu dan mengurangi kesalahan.
Pastikan data contoh sangat mirip dengan skenario dunia nyata, tetapi hindari menyertakan informasi sensitif. Pengguna dapat memodifikasi contoh-contoh ini sesuai kebutuhan.
Konfigurasi Contoh Respons yang Jelas
Setelah mengirim permintaan, panel *debug* menampilkan respons lengkap, termasuk kode status, *header*, dan badan. Sebagai pembuat dokumentasi, konfigurasikan contoh respons yang jelas untuk membantu pengguna memahami kemungkinan hasilnya.
Berikan beberapa contoh respons untuk setiap *endpoint*, seperti sukses (200), permintaan buruk (400), dan tidak sah (401).
Perhatikan secara khusus respons kesalahan, jelaskan dengan jelas kode kesalahan dan format pesan untuk skenario yang berbeda. Ini membantu pengguna dengan cepat mengidentifikasi dan menyelesaikan masalah selama *debugging*.
Berikan Contoh Kode untuk Integrasi
Meskipun Apidog secara otomatis menghasilkan contoh kode untuk bahasa pemrograman umum, kode yang dihasilkan mungkin tidak sepenuhnya selaras dengan kebutuhan bisnis Anda. Dalam kasus seperti itu, sesuaikan contohnya.
Anda dapat mengonfigurasi bahasa mana yang memerlukan contoh yang dibuat secara otomatis di "Pengaturan Proyek -> Pengaturan Fitur Endpoint -> Contoh Kode Permintaan."
Selain itu, Anda dapat menulis contoh kode kustom untuk *endpoint* tertentu di bagian "Deskripsi Endpoint."
Ini memastikan pengguna melihat contoh yang dibuat secara otomatis dan kustom dalam dokumentasi online, membuat integrasi lebih mudah.
Ringkasan
Pengalaman *debugging* dokumentasi online sangat bergantung pada konfigurasi yang tepat. Dengan mengatur URL, autentikasi, struktur parameter, dan contoh dengan cermat, Anda dapat memastikan pengguna dengan cepat memulai API Anda tanpa terbebani oleh detail teknis.