Mengedit spesifikasi API secara manual adalah pekerjaan yang rumit. Mengganti nama field, menambahkan nilai enum, mengencangkan flag yang wajib. Setiap perubahan kecil, tetapi masing-masing harus berada di tempat yang tepat tanpa merusak endpoint yang mereferensikannya. Ini pekerjaan yang presisi, mekanis, dan persis jenis tugas yang akan Anda berikan kepada agen AI, jika saja Anda bisa mempercayainya untuk tidak merusak seluruh skema.
Anda bisa. CLI Apidog memberikan agen semua yang dibutuhkan untuk mengubah spesifikasi secara bertanggung jawab: validasi skema sebelum setiap penulisan, cabang terisolasi untuk bekerja, dan permintaan penggabungan (merge request) untuk Anda tinjau.
Ini adalah panduan *mutasi* sebagai pendamping untuk membiarkan agen membuat dokumentasi API. Membuat bersifat aditif dan berisiko rendah; memperbarui kontrak yang sudah ada adalah bagian di mana pelindung menjadi penting, jadi sebagian besar panduan ini adalah tentang melakukannya tanpa merusak.
Apa Arti "Memperbarui Spesifikasi" di CLI
Spesifikasi Anda di Apidog adalah kumpulan endpoint dan skema data dalam sebuah proyek. Memperbaruinya berarti salah satu dari tiga perintah berikut:
endpoint update: mengubah path, parameter, respons.schema update: mengubah model data yang direferensikan oleh endpoint.import: membawa seluruh file OpenAPI baru untuk diselaraskan dengan proyek.
Sebelum Anda mengarahkan agen ke salah satunya, ada dua perilaku yang harus Anda pahami, karena salah memahaminya adalah cara spesifikasi rusak. Yang pertama adalah model izin, dan yang kedua adalah "jebakan" yang secara diam-diam menghapus data.
Jebakan yang akan menjebak Anda: update adalah penggantian penuh
Ini adalah hal terpenting yang harus Anda ajarkan kepada agen Anda. Perintah `update` CLI **bukan** JSON Patch. Mereka mengirimkan field yang Anda berikan secara langsung; mereka tidak menggabungkan item array berdasarkan ID. Jika Anda mengirim pembaruan dengan array `parameters` parsial yang bermaksud untuk mengubah satu parameter, Anda tidak mengedit parameter tersebut. Anda mengganti seluruh array hanya dengan yang Anda kirim, dan sisanya hilang.
Urutan yang benar selalu baca-modifikasi-tulis pada objek *lengkap*:
# 1. Dapatkan sumber daya lengkap saat ini
apidog endpoint get <endpointId> --project <projectId>
# 2. Edit struktur lengkap secara lokal (simpan setiap field yang tidak Anda ubah)
# 3. Validasi seluruh objek terhadap skema
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json
# 4. Tulis kembali objek lengkap
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
Sertakan ini dalam instruksi agen dengan istilah yang jelas: *jangan pernah mengirim objek parsial untuk `update`; selalu ambil sumber daya lengkap, modifikasi, dan kirimkan kembali secara utuh.* Agen yang melewatkan langkah `get` akan secara diam-diam menghilangkan field. Agen yang menjalankan `cli-schema validate` terlebih dahulu akan menangkap kesalahannya sendiri sebelum mencapai proyek.
Jalur aman: biarkan agen bekerja di cabang AI
Anda bisa memberikan izin edit langsung kepada agen di cabang utama Anda. Jangan, setidaknya tidak untuk permulaan. Apidog memiliki mekanisme isolasi yang dibuat khusus, yaitu **cabang AI**, yang dirancang persis untuk ini: agen memodifikasi sumber daya tanpa menyentuh cabang sumber, dan tidak ada yang digabungkan kembali sampai Anda mengizinkannya. Anggap saja sebagai *pull request* untuk spesifikasi API Anda.
Langkah 1: Buat cabang AI
apidog branch create --project <projectId> --type ai \
--from main --name "ai/20260713-from-main-refund-fields"
Konvensi penamaannya adalah `ai/YYYYMMDD-from-source-feature` sehingga asal dan tujuan cabang mudah dibaca sekilas. Nilai `--from` harus berupa cabang utama Anda atau cabang *sprint* normal, bukan cabang umum. Satu detail praktis: cabang AI yang tidak memiliki perbedaan dari sumbernya akan diarsip secara otomatis setelah 24 jam, sehingga eksperimen yang ditinggalkan akan membersihkan dirinya sendiri.
Langkah 2: Impor sumber daya yang akan diedit agen
Cabang AI dimulai dalam keadaan kosong. Cabang ini tidak mengkloning cabang sumber secara otomatis. Sebelum agen dapat mengedit endpoint atau skema *yang sudah ada*, tarik sumber daya tersebut ke dalam cabang dengan `pick-to`:
apidog branch pick-to --project <projectId> --type ai \
--from main --to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
Sumber daya yang *dibuat* baru oleh agen di cabang tidak memerlukan ini; hanya yang sudah ada yang ingin dimodifikasi atau dihapus. Ini adalah langkah yang sering dilupakan orang: lewati ini, dan agen akan memiliki cabang kosong tanpa ada yang bisa diedit.
Langkah 3: Biarkan agen melakukan perubahan
Sekarang agen menjalankan siklus baca-modifikasi-tulis dari sebelumnya, tetapi dengan `--branch` menunjuk ke cabang AI. Setiap pengeditan terkandung:
apidog endpoint get <endpointId> --project <projectId> \
--branch "ai/20260713-from-main-refund-fields"
apidog endpoint update <endpointId> --project <projectId> \
--branch "ai/20260713-from-main-refund-fields" \
--file ./endpoint-full.json
Cabang utama Anda tidak tersentuh selama ini. Jika agen melakukan kesalahan, dampak kerusakannya hanya pada satu cabang yang bisa dibuang.
Langkah 4: Tinjau, lalu gabungkan
Perubahan pada cabang AI tidak pernah ditulis kembali secara otomatis. Ketika agen selesai, *Anda* yang memutuskan apa yang terjadi. Jika target dilindungi, buka permintaan penggabungan (*merge request*) daripada menggabungkan secara langsung:
apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
--from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>
Tinjau perbedaan (*diff*), setujui, dan perubahan yang telah diverifikasi akan masuk ke cabang utama. Penggabungan langsung dari CLI memerlukan izin edit langsung pada cabang sumber dan target; jika cabang utama dilindungi, lebih baik gunakan `merge-request` dan setujui di klien Apidog.
Contoh kasus: mengganti nama field dengan aman
Aturan abstrak mudah dipahami tetapi sulit diterapkan. Berikut adalah contoh konkret. Katakanlah Anda ingin mengganti nama `amount` menjadi `amountCents` pada model data `Refund`, karena Anda beralih ke representasi *cents* dalam bentuk integer.
Anda memberi tahu agen: *“Ganti nama field `amount` pada skema Refund menjadi `amountCents` dan jadikan itu integer.”* Mengikuti aturannya, agen:
# 1. Ambil skema lengkap saat ini di cabang AI
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"
Ia mendapatkan kembali objek lengkap dan mengedit *seluruh* `jsonSchema`, menjaga setiap field yang tidak disentuhnya:
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
```Perhatikan apa yang *tidak* terjadi: ia tidak hanya mengirim properti yang diubah. Ia mengirim seluruh skema dengan `orderId` dan `reason` utuh, karena `update` menggantikan. Lalu:
# 2. Validasi objek lengkap
apidog cli-schema validate schema-create --file ./refund-full.json
# 3. Tulis kembali ke cabang AI
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json
Anda meninjau perbedaan cabang AI (*diff*) (satu field diganti namanya, tidak ada yang lain yang terganggu) dan menggabungkannya. Itulah seluruh disiplin: objek lengkap, tervalidasi, di cabang, digabungkan setelah tinjauan.
Tandai perubahan yang merusak sebelum Anda menggabungkan
Mengganti nama field yang wajib adalah perubahan yang merusak (*breaking change*): setiap klien yang mengirim `amount` sekarang akan gagal validasi. Set instruksi agen yang baik membuat model *menyatakan hal itu* daripada menggabungkan secara diam-diam. Tambahkan ini ke aturan agen:
Sebelum menggabungkan setiap perubahan spesifikasi, klasifikasikan:
- Tidak merusak (field opsional baru, endpoint baru, batasan yang dilonggarkan) → rangkum dan lanjutkan ke permintaan penggabungan.
- Merusak (field diganti nama/dihapus, field wajib baru, tipe yang diperketat) → HENTIKAN.
Laporkan perubahan yang merusak dan endpoint yang terpengaruh, dan tunggu persetujuan eksplisit dari manusia.
Cabang AI inilah yang membuat hal ini aman untuk ditegakkan: karena tidak ada yang digabungkan secara otomatis, "hentikan dan laporkan" adalah titik pemeriksaan yang nyata, bukan perlombaan melawan penulisan yang sudah terjadi.
Memperbarui dari file OpenAPI sebagai gantinya
Terkadang perubahan sudah ada sebagai file OpenAPI, yang dihasilkan dari kode, diedit di tempat lain, atau diserahkan kepada Anda oleh tim lain. Daripada memutar ulang pengeditan field demi field, agen dapat mengimpor file tersebut untuk menyelaraskannya dengan proyek:
apidog import --project <projectId> --format openapi --file ./openapi.json \
--branch "ai/20260713-from-main-refund-fields"
import menerima OpenAPI 3.x, Swagger 2.0, Postman, dan lainnya. Jalankan terhadap cabang AI terlebih dahulu agar Anda dapat meninjau perubahan spesifikasi yang masuk sebelum mencapai cabang utama. Setelah penggabungan, ekspor spesifikasi yang telah diselaraskan kembali untuk mengonfirmasi hasilnya:
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Rute ini paling baik digunakan ketika sumber kebenaran berada di luar Apidog dan Anda menyinkronkannya. Rute `update` per field paling baik digunakan ketika Apidog *adalah* sumber kebenaran dan Anda melakukan perubahan yang presisi.
Ketika agen melakukan kesalahan: *rollback*
Alasan untuk bekerja di cabang AI adalah karena kesalahan mudah dibatalkan. Jika agen menghasilkan perubahan yang tidak Anda inginkan, Anda tidak pernah menggabungkannya, jadi cabang utama sudah benar. Cukup arsipkan cabang tersebut dan lanjutkan:
apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai
Karena cabang AI tanpa perbedaan yang diterima akan secara otomatis diarsipkan setelah 24 jam, bahkan eksperimen yang terlupakan akan membersihkan dirinya sendiri. Bandingkan itu dengan agen yang mengedit cabang utama secara langsung, di mana `update` yang buruk langsung aktif dan satu-satunya pilihan Anda adalah tempat sampah atau pembalikan manual. Cabang bukanlah birokrasi; itu adalah tombol *undo*.
Catatan tentang izin
Jika `update` atau `import` diblokir, proyek tersebut memiliki Izin Edit AI Eksternal yang dimatikan. Itu adalah gerbang yang disengaja, dan alur cabang AI di atas adalah jawabannya: agen mengedit cabang yang terisolasi dan Anda menyetujui penggabungan. Jika Anda lebih suka memberikan edit langsung, sakelar tersebut berada di Pengaturan Proyek → Pengaturan Fitur → Pengaturan Fitur AI (klien Apidog 2.8.32+). Ketika agen menghadapi tembok izin, jangan biarkan ia secara diam-diam memilih jalan keluar; tampilkan pilihan itu kepada manusia.
Kesulitan umum
Pembaruan parsial menghapus field. Kesalahan paling merusak dan paling umum. `update` menggantikan; ia tidak menggabungkan. Ambil objek lengkap, edit seluruhnya, validasi, lalu tulis. Jika sebuah field hilang, agen mengirimkan payload parsial.Mengedit sumber daya yang ada di cabang AI tanpa mengimpornya. Cabang dimulai dalam keadaan kosong. `pick-to` sumber daya terlebih dahulu, atau agen tidak memiliki apa-apa untuk diedit.`--from` yang salah untuk cabang AI. Sumber harus berupa cabang utama atau cabang *sprint*, tidak pernah cabang umum. Perintah `branch create` akan mengeluh jika Anda salah.Melewatkan validasi. `cli-schema validate` menangkap payload yang salah bentuk di mesin Anda. Agen yang menulis tanpa memvalidasi mengubah salah ketik menjadi panggilan API yang gagal, atau lebih buruk lagi, penggabungan yang buruk.Menggabungkan perubahan yang merusak secara diam-diam. Tanpa aturan klasifikasi terlebih dahulu, agen akan dengan senang hati mengganti nama field yang wajib dan menggabungkannya. Jadikan deteksi perubahan yang merusak sebagai titik pemeriksaan yang eksplisit.
FAQ (Pertanyaan yang Sering Diajukan)
Bisakah saya membiarkan agen mengedit cabang utama secara langsung? Anda bisa, dengan mengaktifkan Izin Edit AI Eksternal, tetapi memulai di cabang AI lebih aman: tidak ada yang masuk ke cabang utama sampai Anda menyetujui penggabungan. Cadangkan pengeditan langsung untuk otomatisasi berisiko rendah dan kepercayaan tinggi.Apa perbedaan antara `branch merge` dan `merge-request`? `branch merge` langsung menulis perubahan dan membutuhkan izin edit langsung pada kedua cabang. `merge-request` membuka permintaan yang dapat ditinjau, pilihan yang tepat ketika cabang utama dilindungi.Apakah agen membutuhkan aplikasi desktop Apidog? Tidak, CLI adalah *standalone*. Aplikasi hanya penting untuk mengaktifkan/menonaktifkan pengaturan Izin Edit AI Eksternal, yang merupakan konfigurasi satu kali.Bagaimana saya memastikan agen tidak mengkhayal nama field? Loop `cli-schema get` → `validate` adalah pelindungnya. Payload dengan field yang dibuat-buat akan gagal validasi secara lokal, sebelum mencapai proyek.
Kesimpulan
Membiarkan agen memperbarui spesifikasi API Anda aman jika tiga hal ini terpenuhi: ia bekerja pada cabang AI yang terisolasi, ia memperlakukan setiap pembaruan sebagai operasi baca-modifikasi-tulis penuh daripada patch, dan manusia menyetujui penggabungan. CLI Apidog memberi Anda ketiga hal tersebut sebagai perintah, yang berarti seluruh siklus (edit, validasi, tinjau) dapat diskrip dan diaudit, dan perubahan yang buruk dapat diatasi hanya dengan satu perintah `archive`.
Siapkan cabang AI, berikan agen aturan baca-modifikasi-tulis dan titik pemeriksaan perubahan yang merusak, dan pemeliharaan spesifikasi menjadi perbedaan (*diff*) yang Anda setujui daripada pekerjaan rumit yang terus Anda tunda. Unduh Apidog untuk mendapatkan CLI, dan gabungkan ini dengan membiarkan agen membuat dokumen Anda untuk mencakup seluruh siklus penulisan dan pemeliharaan.