Anda memiliki *endpoint* yang sudah didefinisikan dan ingin memanggilnya dari aplikasi Anda. Bagian yang membosankan adalah menerjemahkan spesifikasi ke dalam kode yang berfungsi: URL yang benar, *header*, token otentikasi, *query string*, semuanya dihubungkan ke panggilan requests atau fetch. Salah menyalin satu karakter saja dan Anda akan menghabiskan dua puluh menit bertanya-tanya mengapa server mengembalikan 401.
Anda tidak perlu menulis kode *boilerplate* itu secara manual. Jika API Anda dirancang di Apidog, platform ini akan membaca spesifikasi *endpoint* Anda dan memberikan potongan kode permintaan yang siap tempel dalam bahasa yang Anda gunakan: cURL untuk pemeriksaan terminal cepat, Python requests untuk *script*, JavaScript fetch atau Axios untuk *frontend*. Panduan ini akan memandu Anda dalam membuat kode tersebut dari *endpoint* yang sebenarnya, kapan harus mengirim permintaan terlebih dahulu agar potongan kode membawa nilai aktual, dan bagaimana menjaga keakuratan kode yang dihasilkan saat spesifikasi Anda berubah. Jika Anda ingin melihat lebih banyak pilihan, rangkuman kami tentang alat pembuatan kode API memberikan gambaran yang lebih luas; di sini kami akan berfokus pada generator bawaan.
Gagasan ini berpegang pada spesifikasi sebagai satu-satunya sumber kebenaran, prinsip yang sama di balik Spesifikasi OpenAPI. Dapatkan definisi yang benar sekali, dan kode permintaan akan mengikutinya.
Apa yang sebenarnya dilakukan generator kode klien
Apidog mengubah definisi *endpoint* menjadi potongan kode permintaan per varian bahasa. Arahkan ke GET /orders, pilih Python dan pustaka Requests, dan ia akan menulis panggilan yang mengarah ke jalur tersebut dengan *header* dan parameter yang dideklarasikan dalam spesifikasi Anda. Ini adalah generator permintaan: ia menghasilkan kode untuk satu panggilan, dalam sintaksis bahasa dan pustaka HTTP pilihan Anda.
Tetapkan ekspektasi dengan benar pada satu hal. Fitur ini menghasilkan kode permintaan atau klien untuk *endpoint*, bukan SDK lengkap atau paket pustaka klien yang memiliki versi. Jika Anda membutuhkan baris cURL, blok Python requests, atau potongan kode JS fetch untuk dimasukkan ke dalam kode Anda, itulah yang akan Anda dapatkan. Dokumentasi tidak menjelaskan generator pustaka lengkap, jadi jangan berharap SDK berjenis yang dapat diunduh dengan model dan pembantu paginasi yang sudah terpasang.
Ini sangat cocok dengan alur kerja pengembangan API yang mengutamakan desain. Anda mendefinisikan kontrak, menghasilkan kode permintaan langsung darinya, dan setiap konsumen memulai dari definisi yang akurat yang sama daripada tangkapan layar yang ditempel di Slack.
Dua cara untuk membuka generator
Apidog memberi Anda dua titik masuk ke fitur yang sama. Gunakan yang sesuai dengan posisi Anda saat ini.
Yang pertama adalah dari dokumentasi. Buka tab Dokumentasi untuk API Anda, lalu klik tombol Hasilkan Kode Klien di sisi kanan. Ini adalah jalur tercepat ketika Anda sedang membaca dokumentasi *endpoint* dan ingin memanggilnya.
Yang kedua adalah dari *runner*. Di tab Jalankan API, klik ikon kode </>. Ini berada di samping tempat Anda membangun dan mengirim permintaan, jadi ini adalah pilihan alami ketika Anda sudah menguji panggilan tersebut.
Keduanya membuka panel yang sama. Dari sana Anda memilih bahasa dan varian, dan Apidog akan menulis potongan kode tersebut.
Hasilkan panggilan klien Python untuk GET /orders
Berikut adalah alur lengkap dengan *endpoint* yang realistis: panggilan GET /orders yang mencantumkan pesanan pelanggan, difilter berdasarkan status dan dipaginasi.
Langkah 1: buka endpoint dan pilih bahasa Anda
Buka tab Dokumentasi untuk *endpoint* dan klik Hasilkan Kode Klien. Di panel, pilih target Anda. Apidog mendukung daftar panjang bahasa dan varian, sehingga Anda dapat mencocokkan *stack* Anda dengan tepat:
- Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
- JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
- Python: http.client, Requests
- Java: Unirest, OkHttp
- Go: Native
- PHP: cURL, Guzzle, pecl_http, HTTP_Request2
- Lainnya: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R, ditambah opsi HTTP mentah
Untuk contoh ini pilih Python dan varian Requests. Apidog menghasilkan sesuatu seperti ini dari spesifikasi:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {"Accept": "application/json"}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
Salin, masukkan ke dalam *script* Anda, dan itu adalah panggilan yang berfungsi. Itulah jalur *design-first*: potongan kode tersebut mencerminkan dengan tepat apa yang dideklarasikan oleh *endpoint* Anda.
Langkah 2: pahami apa yang disertakan dalam potongan kode hanya spesifikasi
Ada hal penting yang perlu dipahami sebelum Anda menempel. Kode yang dihasilkan langsung dari spesifikasi API hanya mencakup spesifikasi API, bukan nilai parameter permintaan yang sebenarnya atau token otorisasi Anda. Anda mendapatkan bentuk panggilan dan contoh nilai apa pun yang didefinisikan dalam spesifikasi, tetapi bukan *header* Authorization: Bearer ... langsung yang Anda perlukan untuk benar-benar mencapai *endpoint* yang dilindungi.
Itu tidak masalah untuk panggilan tanpa otentikasi atau ketika Anda akan mengisi token sendiri. Untuk GET /orders yang dilindungi, Anda menginginkan nilai yang sebenarnya dalam kode.
Langkah 3: kirim permintaan terlebih dahulu untuk menangkap nilai sebenarnya
Untuk mendapatkan potongan kode yang membawa nilai parameter aktual dan informasi otorisasi, kirim permintaan terlebih dahulu, lalu baca kode dari tab Permintaan Aktual.
Jika Anda bekerja dengan pendekatan *design-first*, ini mudah. Definisikan *endpoint* di tab Edit, klik tab Jalankan, dan parameter permintaan akan terisi secara otomatis dari spesifikasi. Jika Anda lebih suka mengatur semuanya secara manual (mode *request-first*), masukkan parameter permintaan secara manual di tab Jalankan. Bagaimanapun, tambahkan token otentikasi Anda, lalu klik Kirim untuk mengirimkan permintaan.
Setelah respons kembali, beralihlah ke tab Permintaan Aktual dan gulir ke bawah untuk menemukan kode klien. Sekarang potongan kode yang dihasilkan mencakup nilai konkret dan *header* otentikasi yang benar-benar dikirim:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {
"Accept": "application/json",
"Authorization": "Bearer sk_live_51H8xY2..."
}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
Itulah perbedaan antara kedua jalur tersebut. Mode *design-first* mengisi parameter secara otomatis dari spesifikasi; mode *request-first* memungkinkan Anda mengetiknya secara manual. Keduanya akan menghasilkan potongan kode Permintaan Aktual yang sama setelah Anda menekan Kirim. Perlakukan token asli seperti yang di atas sebagai rahasia dan jangan masukkan ke dalam apa pun yang Anda *commit* ke Git; kehati-hatian yang sama seperti yang disarankan dokumentasi Stripe untuk kunci *live* berlaku di sini.
Menangani badan permintaan untuk POST dan PUT
GET /orders tidak memiliki *body*, tetapi saat Anda menghasilkan kode untuk POST /orders atau PUT /orders/{id}, Anda memerlukan *request body* dalam potongan kode. Apidog membantu Anda membangunnya di tab Jalankan sebelum Anda menghasilkan kode.
Untuk *body* JSON atau XML, Anda memiliki dua sumber. Gunakan contoh yang sudah ditentukan dari spesifikasi *endpoint*, atau klik Hasilkan Otomatis untuk membuat struktur *body* yang sesuai dengan skema Anda. *Dropdown* Hasilkan Otomatis memberi Anda dua mode:
- Contoh: pilih contoh *request body* yang sudah ditentukan secara manual.
- Hasilkan Setiap Kali: hasilkan kembali data setiap kali digunakan, mengikuti aturan *mock* cerdas sehingga Anda mendapatkan nilai yang segar dan valid secara skema setiap saat.
Anda dapat mengarahkan bagaimana data dihasilkan melalui sub-opsi Preferensi Hasilkan Otomatis: Gunakan Nilai Contoh Terlebih Dahulu, Gunakan Nilai Default Terlebih Dahulu, Gunakan Nilai Mock, Hasilkan Nama Bidang Saja, dan Gunakan Contoh Permintaan. Pilih Gunakan Nilai Contoh Terlebih Dahulu ketika spesifikasi Anda memiliki contoh yang baik dan Anda ingin contoh tersebut digunakan; pilih Gunakan Nilai Mock ketika Anda ingin data yang dihasilkan realistis untuk setiap bidang.
Catatan versi: opsi Hasilkan Otomatis untuk *request body* memerlukan Apidog versi 2.7.0 atau yang lebih baru. Jika Anda tidak melihatnya, perbarui aplikasi. Skema yang didefinisikan dengan baik beserta contohnya, jenis yang Anda dapatkan dari pembuatan otomatis dokumentasi API dari OpenAPI, membuat langkah ini menghasilkan *body* yang bersih dengan hampir tanpa pengeditan manual.
Ketika Anda membutuhkan nilai yang berubah per permintaan, seperti *timestamp* baru atau ID pesanan acak, masukkan nilai dinamis daripada *hard-coding*. Klik ikon tongkat ajaib di samping kotak input parameter, atau gunakan tombol Sisipkan Nilai Dinamis di dalam *request body* JSON atau XML. Setelah *body* siap, klik Kirim, lalu baca potongan kode yang sudah selesai dari tab Permintaan Aktual seperti sebelumnya.
Kapan menggunakan potongan kode permintaan vs panggilan model bisnis
Sebuah keputusan cepat: berapa banyak kode yang harus Anda salin?
Gunakan potongan kode permintaan tunggal (cURL, fetch, requests.get sederhana) ketika Anda melakukan sesuatu yang bersifat *one-off*. Debugging mengapa sebuah *endpoint* mengembalikan 403, berbagi panggilan yang dapat direproduksi dalam tiket, menjalankan pemeriksaan cepat di terminal, atau menempelkan contoh ke dalam dokumentasi Anda sendiri. Ini bersifat *self-contained* dan tidak memerlukan struktur di sekitarnya.
Condongkan ke kode gaya model bisnis yang lebih lengkap (blok Axios atau requests dengan *header*, parameter, dan penanganan respons yang diatur) ketika panggilan tersebut berada di dalam logika aplikasi yang sebenarnya. Jika GET /orders akan berada dalam modul layanan yang dipanggil dari tiga tempat, Anda menginginkan versi terstruktur yang dapat Anda bungkus dalam sebuah fungsi, tambahkan penanganan kesalahan, dan gunakan kembali. Generator memberikan kedua bentuk tersebut tergantung pada varian yang Anda pilih; sesuaikan bentuknya dengan tempat kode akan berada.
Jika Anda memanggil *endpoint* yang sama dengan otentikasi yang sama di seluruh proyek, seringkali lebih rapi untuk memusatkan bagian-bagian yang dibagi. Panduan kami tentang mengatur parameter global di Apidog menunjukkan cara mendefinisikan *header* dan variabel sekali agar setiap panggilan yang dihasilkan mewarisinya daripada mengulang token di setiap potongan kode.
Jaga akurasi kode yang dihasilkan dengan kebiasaan "spec-first"
Kode yang dihasilkan hanya seakurat spesifikasi di baliknya. Ubah GET /orders untuk menambahkan parameter *query* region dan lupa untuk menghasilkan ulang, dan potongan kode yang Anda salin akan secara diam-diam salah. Solusinya adalah memperlakukan spesifikasi sebagai hal yang Anda pelihara, dan kode sebagai keluaran turunan yang Anda hasilkan ulang sesuai permintaan. Mode *spec-first* Apidog menjaga definisi tetap otoritatif sehingga kode permintaan yang Anda hasilkan selalu mencerminkan kontrak saat ini, bukan yang sudah usang.
Untuk sintaks potongan kode itu sendiri, dokumentasi MDN tentang Fetch API adalah referensi yang kuat ketika Anda ingin memahami atau menyesuaikan varian JavaScript yang dihasilkan Apidog.
Otomatiskan alur kerja dengan Apidog CLI
Pembuatan kode itu sendiri adalah tindakan GUI; Anda menyalin potongan kode dari panel, dan tidak ada perintah CLI terpisah yang mengeluarkan kode klien. Yang dilakukan Apidog CLI dengan baik adalah menjaga dua hal yang menjadi dasar pembuatan kode: spesifikasi yang mutakhir dan pengujian yang berhasil membuktikan bahwa klien yang dihasilkan benar-benar berfungsi.
Instal dengan npm install -g apidog-cli (Node.js v16+) dan otentikasi:
apidog login --with-token <YOUR_ACCESS_TOKEN>
Impor perubahan spesifikasi terbaru agar kode yang Anda hasilkan tetap *current*, dan jalankan skenario pengujian yang tersimpan yang melatih *endpoint* yang dipanggil oleh klien Anda:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Di sini -t adalah ID skenario pengujian, -e adalah ID lingkungan, dan -r adalah *reporter* (cli, html, atau junit). Hubungkan ini ke dalam *pipeline* Anda, seperti yang dijelaskan oleh panduan Apidog CLI GitHub Actions kami, dan setiap *push* memverifikasi bahwa GET /orders masih berfungsi seperti yang dijanjikan oleh spesifikasi sebelum siapa pun menghasilkan ulang klien darinya. CLI tidak menulis kode klien Anda, tetapi ia menjaga kontrak yang menjadi dasar kode tersebut.
FAQ
Apakah kode yang dihasilkan menyertakan kunci API dan token saya?
Tidak secara *default*. Kode yang dihasilkan hanya dari spesifikasi API hanya mencakup spesifikasi, bukan nilai parameter yang sebenarnya atau otorisasi. Untuk mendapatkan potongan kode dengan token dan nilai aktual Anda, kirim permintaan terlebih dahulu, lalu baca kodenya dari tab Permintaan Aktual. Perlakukan token apa pun dalam potongan kode tersebut sebagai rahasia.
Bahasa dan pustaka apa saja yang dapat digunakan Apidog untuk menghasilkan kode?
Banyak pilihan. Shell (cURL, Httpie, wget, PowerShell), JavaScript (Fetch, Axios, jQuery, XHR, dan lainnya), Python (http.client dan Requests), Java (Unirest, OkHttp), Go, PHP, Swift, C, C#, Ruby, Dart, R, dan lainnya. Anda memilih bahasa dan varian spesifik di panel generator.
Mengapa saya tidak melihat opsi Hasilkan Otomatis untuk *request body*?
Opsi-opsi tersebut memerlukan Apidog versi 2.7.0 atau yang lebih baru. Perbarui aplikasi dan mereka akan muncul di tab Jalankan ketika Anda membuat *body* JSON atau XML. Setelah tersedia, *dropdown* Hasilkan Otomatis menawarkan Contoh dan Hasilkan Setiap Kali, dengan sub-opsi preferensi tentang bagaimana nilai dihasilkan.
Apakah pembuatan kode klien merupakan fitur berbayar?
Dokumentasi Apidog tidak menarik garis antara gratis-versus-berbayar atau *cloud*-versus-*self-hosted* untuk pembuatan kode klien. Satu-satunya persyaratan versi yang disebutkan di mana pun adalah bahwa opsi Hasilkan Otomatis untuk *request body* memerlukan versi 2.7.0 atau yang lebih baru. Anda dapat mengunduh Apidog dan mencoba generatornya tanpa paket berbayar.
Bagaimana cara memastikan panggilan yang dihasilkan benar-benar berfungsi?
Hasilkan potongan kode, lalu verifikasi *endpoint* dengan pengujian yang tersimpan. Panduan kami tentang menulis skenario pengujian dengan Apidog menunjukkan cara membangunnya, dan CLI dapat menjalankannya di CI sehingga kontrak yang rusak akan menyebabkan *build* gagal sebelum Anda menghasilkan ulang klien darinya.
Ringkasan
Menghasilkan kode klien di Apidog mengubah spesifikasi *endpoint* menjadi permintaan siap tempel dalam bahasa apa pun yang Anda gunakan, dan tab Permintaan Aktual adalah trik untuk mendapatkan nilai dan otentikasi nyata ke dalam potongan kode tersebut alih-alih templat kosong. Pertahankan spesifikasi sebagai yang otoritatif, hasilkan ulang saat berubah, dan biarkan pengujian yang tersimpan mengkonfirmasi bahwa panggilan masih berfungsi. Unduh Apidog untuk mengikuti, definisikan *endpoint* GET /orders Anda, dan salin panggilan klien yang berfungsi dalam beberapa klik.