Anda membutuhkan API palsu untuk membangun. Backend belum siap, atau layanan pihak ketiga memiliki batasan kecepatan (rate-limited), atau Anda hanya ingin tes Anda berjalan tanpa menyentuh server langsung. Jawaban yang biasa adalah *mock*. Pertanyaannya adalah bagaimana Anda membangunnya.
Anda dapat mengklik melalui GUI untuk menentukan rute dan respons standar. Itu baik untuk sekali. Namun, *mock* yang Anda bangun secara manual di aplikasi desktop sulit untuk direproduksi, sulit untuk di-versi, dan mustahil bagi CI atau agen pengkodean AI untuk membuatnya kembali sendiri. Sebuah *mock* yang Anda definisikan dari baris perintah berbeda. Ini adalah perintah dalam skrip, langkah dalam *pipeline*, baris yang dapat dijalankan oleh agen. Apa yang Anda ketik, mesin juga bisa mengetiknya.
Panduan ini mencakup dua jalur. Pertama, jalur *open-source* umum: server *mock* *single-binary* yang Anda jalankan langsung dari file, sehingga spesifikasi atau file JSON menjadi *endpoint* langsung dalam satu perintah. Kemudian jalur CLI Apidog, yang bekerja secara berbeda dan patut dipahami dengan caranya sendiri. Jika Anda ingin melihat lanskap opsinya terlebih dahulu, rangkuman kami tentang alat *mock* API terbaik dan panduan alat *mocking* API REST keduanya memberikan Anda pandangan yang lebih luas.
Jalur umum: menjalankan server *mock* dari sebuah file
*Mock* CLI klasik adalah *binary* kecil yang Anda arahkan ke sebuah file. Berikan spesifikasi atau file data, dan ia akan menyajikan *endpoint* HTTP nyata pada porta lokal. Tidak ada proyek, tidak ada *login*, tidak ada akun. Alat-alat ini melakukan satu hal: mengubah file menjadi API palsu yang bisa Anda panggil. Tiga di antaranya mencakup hampir setiap kasus.
Prism: menyajikan spesifikasi OpenAPI
Jika Anda sudah memiliki file OpenAPI, Prism dari Stoplight adalah *mock* dengan upaya terendah yang dapat Anda jalankan. Ia membaca paths, contoh, dan skema Anda, kemudian menyajikan respons yang sesuai dengan kontrak.
npx @stoplight/prism-cli mock ./openapi.yaml
Itu akan memulai server di http://127.0.0.1:4010 dengan setiap operasi dalam spesifikasi Anda terhubung. Prism mengembalikan example yang Anda definisikan untuk respons, atau menghasilkan respons acak yang valid dari skema jika Anda mengosongkannya. Ia juga memvalidasi permintaan masuk terhadap spesifikasi, sehingga panggilan yang salah format mendapatkan 422 yang tepat, bukan *pass* yang diam. Panggil untuk memeriksa apakah ia berfungsi:
curl http://127.0.0.1:4010/orders/123
Prism tidak memiliki status (stateless), jadi POST tidak menyimpan apa pun. Itu intinya ketika Anda ingin *mock* tetap jujur pada kontrak. Untuk instalasi global, jalankan npm install -g @stoplight/prism-cli dan hilangkan npx.
Mockoon CLI: menjalankan file data tanpa GUI (headless)
Mockoon CLI menjalankan *mock* dari file data, baik yang Anda ekspor dari aplikasi desktop Mockoon gratis atau spesifikasi OpenAPI biasa. Aplikasi desktop memungkinkan Anda membangun rute secara visual; CLI menjalankan lingkungan yang sama tanpa GUI (headless) di CI atau di server.
npx @mockoon/cli start --data ./env.json
Arahkan --data ke file lingkungan Mockoon atau file JSON/YAML OpenAPI dan ia akan segera menyajikan, *default* ke porta 3000. Tambahkan --port untuk mengubahnya. Jika file data berasal dari versi Mockoon yang lebih lama, CLI memigrasikannya dalam memori tanpa menyentuh aslinya. Instal secara global dengan npm install -g @mockoon/cli untuk perintah mockoon-cli yang persisten. Ini adalah pilihan yang baik ketika Anda menginginkan rute yang lebih kaya, yang disesuaikan secara manual daripada yang diberikan oleh spesifikasi biasa, dan masih ingin menjalankannya tanpa GUI. Sebuah server *mock* ringan untuk API RESTful seringkali cocok di sini.
json-server: memalsukan API REST dari JSON
Ketika Anda belum memiliki spesifikasi, json-server adalah jalur tercepat. Anda menulis file JSON biasa yang menjelaskan data Anda, dan ia membangun API REST lengkap di sekitarnya.
npx json-server db.json
Dengan db.json yang berisi array posts, itu menyajikan http://localhost:3000/posts dengan GET, POST, PUT, PATCH, dan DELETE yang nyata. Sebuah POST benar-benar menambahkan catatan dan menuliskannya kembali ke file, sehingga Anda mendapatkan perilaku *stateful* secara gratis, yang tidak akan diberikan oleh Prism. Anda juga mendapatkan pemfilteran, pengurutan, dan paginasi melalui parameter kueri. Instal secara global dengan npm install -g json-server jika Anda ingin selalu ada di PATH Anda.
Itu adalah jalur *open*. Setiap alat adalah *binary* tunggal, berjalan dari satu file, dan tidak membutuhkan apa pun lagi. Kekurangannya adalah setiap alat adalah pulau sendiri. *Mock* hidup terpisah dari desain asli Anda, tes Anda, dan dokumen Anda, dan Anda menjaga file serta proses yang berjalan tetap sinkron sendiri. Jika Anda membutuhkan pencocokan permintaan atau pemutaran ulang yang tepat, MockServer dan WireMock menawarkan kemampuan yang lebih dalam, dengan biaya *runtime* Java.
Jalur CLI Apidog: mengimpor spesifikasi, membuat skrip ekspektasi
Apidog melakukan *mock* secara berbeda, dan memahami ini dengan benar akan menyelamatkan Anda dari kebingungan. CLI apidog tidak memulai server *mock* lokal dari sebuah file. Tidak ada apidog mock ./openapi.yaml. Sebagai gantinya, Apidog menghosting *mock* untuk Anda, dan CLI adalah cara Anda memberinya spesifikasi dan membuat skrip respons kustom.
Satu catatan jujur terlebih dahulu. Apidog bukanlah *open source*; ini adalah produk komersial dengan tingkatan gratis. Apa yang ditawarkan tingkatan gratis ditambah CLI adalah proyek terintegrasi, sehingga *mock*, desain, dan tes berbagi satu sumber kebenaran alih-alih tiga file terpisah dan tiga proses terpisah. Jika *mock* sekali pakai dari satu file adalah semua yang Anda butuhkan, alat yang lebih ringan akan menang. Jika *mock* Anda harus tetap selaras dengan API Anda yang sebenarnya saat berubah, bacalah terus.
Instal dan autentikasi terlebih dahulu (Panduan instalasi Apidog CLI mencakup pengaturan token):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Impor spesifikasi untuk mendapatkan *mock* pintar yang di-hosting
Langkah pertama adalah memasukkan API Anda ke dalam sebuah proyek. Impor file OpenAPI, dan Apidog secara otomatis menghasilkan URL *mock* untuk setiap *endpoint*.
apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Di sinilah Apidog berbeda dari Prism dan json-server. Anda tidak menjalankan server; impor memberi Anda *mock* pintar yang di-hosting untuk setiap operasi. *Smart mock* membaca tipe dan nama bidang skema Anda, sehingga bidang email mengembalikan email yang masuk akal dan createdAt mengembalikan *timestamp* yang terlihat nyata, bukan string acak. apidog import juga menerima format Swagger 2.0, Postman, dan Apidog, sehingga definisi yang ada menjadi *mock* langsung dalam satu perintah.
Membuat skrip respons kustom dengan apidog mock
*Mock* yang dibuat secara otomatis mencakup kasus umum. Ketika Anda membutuhkan respons spesifik untuk permintaan spesifik, misalnya 200 untuk satu ID pengguna dan 404 untuk ID lainnya, Anda menambahkan ekspektasi *mock*. Inilah yang dikelola oleh grup perintah apidog mock, dan ini adalah operasi CRUD pada ekspektasi tersebut, bukan server yang Anda mulai.
apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Daftar mengembalikan JSON terstruktur, sehingga Anda dapat menyaringnya melalui jq untuk menemukan ID ekspektasi dan memasukkannya ke perintah berikutnya. Untuk membaca, mengubah, atau menghapusnya:
apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Subperintah create dan update menerima --file yang menjelaskan ekspektasi. Pastikan bentuknya benar sebelum Anda menuliskannya, dibahas selanjutnya.
Validasi file ekspektasi sebelum Anda menuliskannya
Jangan menebak-nebak JSON. CLI mengirimkan skema untuk setiap penulisan, jadi Anda mengambil bentuknya, mengisinya, dan memvalidasi sebelum penulisan yang sebenarnya. Ekspektasi yang salah format akan gagal dengan cepat alih-alih mendarat secara diam-diam.
apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Ambil skema, tulis mock.json Anda agar sesuai, validasi, lalu buat. Jika validasi mengembalikan *exit code* bukan nol, *pipeline* berhenti sebelum file yang buruk mencapai proyek Anda. Jalankan tiga langkah yang sama untuk pembaruan dengan kunci skema mock-update. Setiap perintah mengembalikan JSON dengan blok agentHints.nextSteps yang memberi tahu Anda, atau agen, apa yang harus dijalankan selanjutnya, yang membuat alur ini dapat digunakan oleh alat pengkodean AI dan bukan hanya manusia. Panduan lengkap Apidog CLI memetakan sisa grup perintah.
Menghubungkannya ke CI
Kedua jalur cocok untuk sebuah *pipeline* karena setiap perintah memiliki *exit code* dan *text output*. Sebuah *mock* berbasis server dan tes integrasi dalam *job* yang sama mungkin terlihat seperti ini:
# mulai Prism di latar belakang, lalu jalankan tes terhadapnya
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!
npm test
kill $PRISM_PID
Alur Apidog berbeda bentuknya: tidak ada proses lokal untuk memulai dan menghentikan, karena *mock* di-hosting. Anda memvalidasi dan menerapkan ekspektasi sebagai langkah penyiapan, dan tes Anda langsung mengenai URL *mock* yang di-hosting.
# pastikan ekspektasi terbentuk dengan baik, lalu terapkan
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Bagaimanapun, tidak ada yang mengklik tombol. Itulah seluruh alasan untuk melakukan *mock* dari CLI: tim *spec-first*, *job* CI, dan agen AI semuanya dapat membangun API palsu yang sama dari perintah yang sama.
Hambatan umum
Mengharapkan apidog mock untuk memulai server. Itu tidak akan terjadi. Tidak ada apidog mock start, apidog mock serve, atau apidog mock ./file.yaml. Anda melakukan apidog import spesifikasi untuk mendapatkan *mock* yang di-hosting, dan apidog mock mengelola ekspektasi kustom di atasnya. Jika Anda ingin proses lokal yang Anda luncurkan dari sebuah file, itu adalah Prism, Mockoon CLI, atau json-server.
Melewati langkah skema pada penulisan. apidog mock create dan update menerima --file, dan bentuk yang salah akan gagal atau menulis sesuatu yang tidak Anda inginkan. Selalu jalankan cli-schema get dan cli-schema validate terlebih dahulu. Ini adalah dua perintah ekstra dan menghemat sesi *debugging* Anda.
Prism terlihat kosong karena spesifikasi Anda tipis. *Mock* Prism hanya sebaik contoh Anda. Jika sebuah respons tidak memiliki example dan skema yang samar, Anda mendapatkan data yang samar. Tambahkan contoh ke spesifikasi dan *mock* akan menjadi lebih tajam.
Ekspektasi *stateful* dari alat *stateless*. *Mock* kontrak Prism dan Apidog tidak menyimpan penulisan. Jika Anda membutuhkan POST kemudian GET untuk mengembalikan catatan baru, gunakan json-server atau ekspektasi Apidog yang mengembalikan bentuk yang Anda inginkan.
Kesimpulan
Melakukan *mock* dari CLI mengubah tugas yang banyak klik menjadi perintah yang dapat Anda skrip, tinjau, dan serahkan ke CI atau agen. Jalur *open* memberi Anda server *single-binary* yang Anda jalankan dari sebuah file: Prism untuk spesifikasi OpenAPI, Mockoon CLI untuk file data tanpa GUI, json-server untuk API REST instan dari JSON. Jalur Apidog bekerja dengan cara lain; Anda mengimpor spesifikasi sekali untuk mendapatkan *mock* pintar yang di-hosting, lalu membuat skrip respons kustom dengan apidog mock dan pelindung validasi cli-schema.
Pilihlah berdasarkan apa yang sudah Anda miliki dan di mana *mock* itu perlu hidup. Jika Anda ingin server sekali pakai dari satu file, alat *open* sangat cocok. Jika Anda ingin *mock* tetap selaras dengan desain dan tes Anda dalam satu proyek, Unduh Apidog, instal CLI, dan bangun *mock* Anda tanpa menyentuh mouse.