Ada dua kubu di setiap tim API tempat saya bekerja.
Satu kubu menulis spesifikasi OpenAPI mereka secara manual, menyimpannya ke direktori specs/, dan menganggap Git sebagai sumber kebenaran. Kubu lainnya mengklik melalui desainer visual, mengekspor spesifikasi ketika CI mengeluh, dan menambal perbedaan apa pun yang telah terakumulasi oleh kedua representasi sejak Selasa lalu.
Saya pernah berada di kedua kubu. Kubu pertama lebih lambat di hari pertama dan lebih cepat di hari kesembilan puluh. Kubu kedua justru sebaliknya. Dan hingga sekitar sebulan yang lalu, alat desain API yang paling sering saya gunakan — Apidog — hanya benar-benar melayani kubu kedua. Desainer visualnya luar biasa. Fitur YAML round-trip-nya adalah sesuatu yang harus Anda pertahankan dalam tinjauan kode.
Kemudian pada pertengahan April, Mode Spesifikasi-Pertama (Beta) muncul di dialog Proyek Baru. Saya sengaja tidak menulis tentangnya pada hari peluncuran. Saya ingin menggunakannya pada sesuatu yang nyata terlebih dahulu, dan saya ingin menunggu cukup lama agar bug-bug awal minggu memiliki kesempatan untuk muncul. Sebulan adalah waktu yang kira-kira tepat. Postingan ini adalah apa yang saya temukan setelah menghabiskan pagi hari dengan versi beta ini menggunakan spesifikasi OpenAPI dari salah satu proyek sampingan saya — apa yang akan saya katakan kepada rekan setim sebelum mereka mencobanya, dan di mana ia cocok serta tidak cocok.
Apa yang Sebenarnya Diubah oleh Mode Spesifikasi-Pertama
Versi singkatnya: Apidog kini memiliki dua mode proyek, dan secara mendasar keduanya adalah produk yang benar-benar berbeda.
Mode default adalah apa yang kebanyakan orang tahu. Anda mengklik + Proyek Baru, Anda mendapatkan struktur folder dan formulir visual, dan Anda membangun endpoint dengan mengisi kolom. Spesifikasi OpenAPI dihasilkan secara internal. Ini berfungsi, terutama untuk tim yang belum memiliki kebiasaan kuat dalam menggunakan YAML.
Mode Spesifikasi-Pertama menggantikan editor formulir dengan editor kode sungguhan untuk file .yaml dan .json mentah, ditambah sinkronisasi dua arah ke repositori Git Anda. Spesifikasi OpenAPI Anda adalah file di disk, bukan serialisasi dari klik. Ada penyorotan sintaks, autocompletion terhadap skema OpenAPI, dan panel "Penguraian Direktori Waktu Nyata" yang membangun kerangka endpoint di bilah samping dari kode Anda saat Anda mengetik.
Detail terakhir itu adalah yang akan saya tekankan jika saya mendemokan ini kepada orang yang skeptis. Alasan desainer visual ada bukan karena YAML sulit — melainkan karena YAML menyembunyikan struktur sampai Anda sudah menggulirnya. Tampilan kerangka Apidog memecahkan masalah itu tanpa membuat Anda meninggalkan file. Anda menulis spesifikasi, Anda mendapatkan navigasi. Keduanya hidup berdampingan di layar.
Tesisnya, jika ada: pengembangan berbasis spesifikasi tidak pernah tentang memilih editor teks. Ini tentang siapa yang memiliki artefak. Mode Spesifikasi-Pertama menjadikan artefak sebagai file di repo Anda, titik. UI adalah jendela ke sana, bukan pembungkus di sekitarnya.
Pengaturan, menyeluruh
Inilah langkah-langkah yang saya ikuti. Butuh waktu kurang dari sepuluh menit, sebagian besar untuk otorisasi Git.
1. Buat proyek dalam mode yang benar. Dari layar proyek, + Proyek Baru → Umum → Mode Spesifikasi-Pertama. Pemilih mode mudah terlewat jika Anda sudah setahun membuat proyek secara otomatis — Mode Umum ditandai "Direkomendasikan" dan mata Anda langsung melewati ubin kedua. Pelankan langkah di sini.
2. Hubungkan ke repositori Git Anda. Gulir ke Hubungkan dengan Repositori Git dan otorisasi penyedia Anda. Saya menggunakan GitHub; dokumentasi mencakup yang lain. Kemudian pilih Organisasi, Repositori, dan Cabang utama. Apidog akan menyinkronkan file spesifikasi di cabang tersebut sebagai salinan kerja Anda.
3. Konfigurasi proyek. Masukkan Nama Proyek, atur izin tim, dan Buat. Sinkronisasi pertama akan menarik semua file .yaml dan .json yang ada di repo ke ruang kerja Apidog.
4. Edit spesifikasi seperti file, bukan formulir. Buka salah satu file YAML. Anda akan mendapatkan editor sungguhan, autocompletion yang memahami skema, dan kerangka endpoint yang muncul di bilah samping saat Anda mengetik. Jika Anda pernah menghabiskan waktu di VS Code dengan ekstensi OpenAPI, ini akan terasa familier — kecuali kerangka tersebut terhubung ke navigasi, dan mengklik sebuah endpoint akan langsung melompat ke baris yang benar.
5. Commit dan push. Kanan atas, Commit & Push. Dialog terbuka ke bagian Perubahan yang mencantumkan file yang dimodifikasi, kolom Pesan Commit, dan dua tombol: Push atau Buang semua perubahan. Tidak ada langkah staging terpisah — apa pun di bagian Perubahan akan masuk ke commit. Itu adalah penyederhanaan yang disengaja, dan untuk sebagian besar alur kerja pengeditan spesifikasi, ini adalah pilihan yang tepat.
6. Perhatikan indikator sinkronisasi. Pojok kiri bawah — Anda dapat melihatnya sebagai Baru saja disinkronkan di Gambar 1. Ini memberitahu Anda apakah perubahan lokal Anda sudah di-push, di-pull, atau tidak sinkron dengan remote. Saya membiarkannya terbuka di sudut layar saya dan itu menjadi hal yang lebih saya percaya daripada dialog modal. Jika indikator berwarna hijau, Anda dan repo sepakat.
Itu adalah seluruh area antarmuka. Enam langkah, tanpa mesin sinkronisasi terpisah untuk dikonfigurasi, tanpa plugin untuk diinstal.
Apa yang Saya Perhatikan yang Tidak Tercantum dalam Dokumentasi
Tiga hal yang patut dicatat, semuanya dari pagi hari saya mengutak-atiknya.
Tampilan kerangka diperbarui lebih cepat dari yang saya duga. Saya pernah menggunakan beberapa "editor OpenAPI langsung" di masa lalu dan sebagian besar di antaranya mengurai ulang saat menyimpan, yang berarti ada penundaan 30 detik antara menambahkan endpoint dan melihatnya di bilah samping. Kerangka Apidog diperbarui saat saya mengetik — cukup instan sehingga saya berhenti memeriksanya. Itu terdengar seperti hal kecil. Tapi tidak. Itu adalah perbedaan antara mempercayai kerangka sebagai alat navigasi versus memeriksanya sebagai laporan status.
Integrasi Git benar-benar dua arah. Saya mengedit file yang sama di kloning lokal saya dan melakukan push dari terminal saat Apidog terbuka. Apidog menyadarinya, indikator sinkronisasi berubah menjadi "tertinggal", dan satu klik menarik perubahan ke editor tanpa dialog merge. Sinkronisasi dua arah yang dijanjikan dokumentasi adalah pengalaman nyata, bukan ringkasan pemasaran. Jika Anda memiliki rekan setim yang menolak menggunakan apa pun selain Vim, mereka dapat terus menggunakan Vim, dan Anda dapat terus menggunakan Apidog, dan file di repo tetap menjadi satu-satunya hal yang kalian berdua edit.
Tidak ada jalan kembali ke desainer visual dalam proyek yang sama. Ini disengaja, tetapi patut diketahui sebelum Anda berkomitmen. Jika Anda memilih Mode Spesifikasi-Pertama saat pembuatan, proyek itu adalah spesifikasi-pertama. Anda tidak dapat mengganti proyek di tengah jalan karena model data di bawahnya berbeda. Untuk tim yang menginginkan kedua mode pada spesifikasi yang sama, alur kerjanya adalah: simpan spesifikasi di repo, arahkan proyek Spesifikasi-Pertama ke sana, dan biarkan pengguna mode visual membuka proyek terpisah yang mengimpor dari sumber yang sama. Tidak mulus, tetapi bisa diterapkan.
Di mana Cocok, dan Di mana Tidak
Saya akan menggunakan ini dalam produksi. Itu adalah jawaban paling langsung yang bisa saya berikan. Kombinasi editor sungguhan, autocompletion yang menghormati skema OpenAPI, dan indikator sinkronisasi yang dapat saya percayai adalah yang saya inginkan dari Apidog selama dua tahun.
Tapi inilah versi jujur tentang siapa ini ditujukan.
Ini cocok jika Anda sudah menulis OpenAPI secara manual, atau ingin melakukannya. Ini cocok jika CI Anda menjalankan spectral lint atau menghasilkan SDK klien dari spesifikasi dan spesifikasi harus disimpan di Git. Ini cocok jika Anda memiliki seorang insinyur di tim yang sebaliknya akan membuka pull request terhadap file YAML dari VS Code, dan Anda ingin semua orang berkumpul pada satu alat tanpa memaksa mereka meninggalkan keyboard mereka. Dan ini sangat cocok jika Anda telah mengelola perbedaan antara "spesifikasi di Apidog" dan "spesifikasi di repo" dengan langkah make export yang tidak dipercaya siapa pun.
Ini tidak cocok jika tim Anda belum pernah menyentuh OpenAPI dan desainer visual adalah alasan mereka dapat berkontribusi. Untuk tim-tim tersebut, mode default tetap merupakan pilihan yang tepat. Mode Spesifikasi-Pertama mengorbankan kemudahan orientasi demi ketepatan, dan pertukaran itu salah ketika sebagian besar kontributor Anda bukan spesialis API.
Ini juga belum cocok untuk tim yang perlu menggabungkan kedua mode pada proyek yang sama. Versi beta ini benar-benar beta dalam hal itu. Saya berharap ini akan melunak dalam beberapa rilis berikutnya.
Intinya
Pengembangan berbasis spesifikasi dulu berarti tidak menggunakan alat desain API. Anda bisa hidup dengan YAML dan mengorbankan test runner serta mock server, atau Anda bisa hidup dengan desainer visual dan mengorbankan Git sebagai sumber kebenaran. Langkah menarik dalam Mode Spesifikasi-Pertama adalah Apidog berhenti meminta Anda untuk memilih.
File di repo Anda adalah file di editor. Kerangka adalah tampilan, bukan status. Sinkronisasi Git adalah penghubung, bukan fitur. Jika Anda telah menunggu platform API untuk menganggap serius spesifikasi-pertama alih-alih memperlakukannya sebagai opsi ekspor, inilah yang akan saya coba.
Versi beta sudah tersedia di dialog Proyek Baru hari ini. Unduh Apidog, pilih Mode Spesifikasi-Pertama saat pembuatan, dan arahkan ke repo yang sudah Anda percayai. Commit pertama membutuhkan sepuluh menit. Keputusan untuk mempertahankannya membutuhkan waktu sekitar seminggu.