Modul API Apidog memberi Anda dua cara untuk membangun hal yang sama: kontrak API. Satu menggunakan formulir visual. Yang lainnya menggunakan editor kode mentah yang terhubung ke Git. Keduanya menghasilkan OpenAPI yang valid. Perbedaannya adalah bagaimana tim Anda bekerja sehari-hari, dan mana yang cocok lebih sedikit tergantung pada alat dan lebih banyak pada kebiasaan Anda.
Panduan ini membahas keputusan design-first vs spec-first di Apidog: apa itu setiap mode, bagaimana mereka menangani Git, dan tim mana yang cenderung memilih yang mana. Anda beralih di antara keduanya dari satu tombol di kiri bawah modul API, sehingga pilihan tidak permanen. Tetapi memilih default yang tepat akan menghemat friksi.
Dua filosofi
Sebelum mode, ada pola pikir. Kedua pendekatan berbagi satu aturan: Anda menentukan kontrak API sebelum Anda menulis implementasinya. Kontrak adalah sumber kebenaran. Kode, pengujian, mock, dan dokumen semuanya mengalir dari sana.
Design-first berarti Anda membentuk kontrak tersebut melalui antarmuka yang terstruktur. Anda menambahkan endpoint, parameter, dan skema melalui formulir dan daftar pilihan. Alat ini menjamin bahwa output valid karena Anda hanya dapat memasukkan nilai yang valid.
Spec-first (sering disebut contract-first) berarti Anda menulis kontrak secara langsung sebagai file spesifikasi: OpenAPI dalam YAML atau JSON. Spesifikasi *adalah* permukaan kerja Anda. Anda mengeditnya seperti kode sumber.
Istilah-istilah ini saling tumpang tindih dalam praktik. "Contract-first" dan "spec-first" adalah sinonim, dan banyak tim menggunakan "design-first" secara longgar untuk berarti pendekatan apa pun di mana kontrak mendahului kode. Perbedaan yang berguna di sini adalah konkret: di Apidog, satu mode memberi Anda formulir, yang lain memberi Anda editor teks. Itulah batasan yang penting saat Anda memilih.
Penting untuk memisahkan keduanya dari pengembangan API design-first vs code-first. Code-first menghasilkan spesifikasi *dari* anotasi dalam implementasi Anda, sehingga kode yang memimpin. Kedua mode Apidog menjaga kontrak di depan kode. Mereka hanya berbeda pendapat tentang bagaimana Anda menuliskannya. Untuk gambaran yang lebih luas tentang memperlakukan spesifikasi Anda sebagai artefak berversi, lihat gambaran umum kami tentang alur kerja API Git-native.
Mode Design-First Apidog
Mode Design-First adalah desainer visual. Anda membangun endpoint melalui antarmuka terpandu: pilih metode, beri nama path, tambahkan parameter kueri dan path, definisikan skema permintaan dan respons melalui editor pohon, dan lampirkan contoh. Apidog merender OpenAPI yang mendasarinya untuk Anda di latar belakang.
Mode ini adalah default untuk sebagian besar tim, dan dengan alasan yang bagus. Anda tidak perlu mengingat sintaks OpenAPI. Editor skema menerapkan struktur, sehingga Anda tidak dapat mengirimkan spesifikasi dengan tanda kurung yang salah tempat atau tipe yang tidak valid. Komponen yang dapat digunakan kembali, seperti skema Error bersama atau header umum, hanya dengan beberapa klik.
Mode Design-First juga mendukung branch, sehingga tim dapat bekerja pada versi desain API yang terpisah secara paralel dan merekonsiliasikannya nanti. Peninjau melihat perbedaan terstruktur daripada teks mentah, yang membuat perubahan kontrak lebih mudah dibaca bagi orang yang tidak terbiasa dengan YAML.
Risikonya: Anda bekerja melalui abstraksi. Jika Anda sudah berpikir dalam OpenAPI, formulir bisa terasa seperti klik tambahan antara Anda dan spesifikasi yang ada di kepala Anda.
Mode Spec-First Apidog
Mode Spec-First, saat ini dalam versi beta, membalikkan hal itu. Alih-alih formulir, Anda mendapatkan editor kode gaya IDE dan Anda menulis spesifikasi OpenAPI atau Swagger langsung dalam YAML atau JSON. Ini dibangun untuk tim yang ingin definisi API mereka berada di Git seperti file sumber lainnya.
Editor berperilaku seperti editor kode Anda: penyorotan sintaks, validasi sebaris, dan pelengkapan otomatis yang disesuaikan untuk skema OpenAPI dan Swagger. Saat Anda mengetik, bilah sisi kiri secara otomatis mengurai spesifikasi Anda menjadi kerangka jalur dan komponen, sehingga Anda dapat menavigasi file besar tanpa perlu menggulir. Indikator sinkronisasi menunjukkan apakah edit lokal Anda selaras dengan repositori yang terhubung.
Fitur utamanya adalah sinkronisasi Git dua arah. Anda menghubungkan repositori di GitHub atau GitLab (Azure DevOps berfungsi melalui Koneksi Git generik), dan Apidog menyinkronkan file spesifikasi Anda di kedua arah. Edit di Apidog, lalu commit dan push langsung dari aplikasi. Atau edit spesifikasi di editor kode Anda, push dari sana, dan tarik perubahan kembali ke Apidog. File spesifikasi adalah kebenaran yang dibagikan, dan kedua permukaan tetap selaras. Anda dapat membaca pengaturan lengkapnya di dokumen Mode Spec-First.
Mode ini memperlakukan kontrak API Anda seperti Anda memperlakukan artefak kode lainnya: ditinjau dalam permintaan tarik, diviralkan bersama layanan yang mengimplementasikannya, dan dibandingkan baris demi baris. Jika itu adalah cara tim Anda sudah mengelola infrastruktur dan konfigurasi, lihat pandangan kami yang lebih dalam tentang spesifikasi API sebagai kode untuk alasan di baliknya.
Perbandingan berdampingan
Kedua mode menghasilkan OpenAPI yang sama dan mendukung mocking, pengujian, serta dokumen hilir. Mereka berbeda dalam cara Anda menulis dan memversi spesifikasi.
| Mode Design-First | Mode Spec-First (beta) | |
|---|---|---|
| Editor | Formulir visual dan pohon skema | Editor kode YAML/JSON bergaya IDE |
| Format spesifikasi | OpenAPI (dihasilkan untuk Anda) | OpenAPI / Swagger, ditulis secara manual |
| Alur kerja Git | Dukungan branch di dalam Apidog | Sinkronisasi dua arah dengan GitHub, GitLab, Azure DevOps (Koneksi Git); commit dan push dari aplikasi |
| Validasi | Diberlakukan oleh input formulir | Validasi sintaks sebaris dan pelengkapan otomatis |
| Navigasi | Daftar endpoint dan folder | Kerangka yang diurai otomatis di bilah sisi kiri |
| Kurva pembelajaran | Rendah; tidak perlu pengetahuan OpenAPI | Lebih tinggi; mengasumsikan kefasihan OpenAPI |
| Terbaik untuk | Tim dengan beragam keahlian, orientasi cepat | Insinyur yang memperlakukan spesifikasi sebagai kode |
Tim mana yang harus memilih yang mana
Gunakan Mode Design-First jika semua kontributor Anda bukan ahli OpenAPI. Manajer produk, QA, dan insinyur junior semuanya dapat menambah atau meninjau endpoint tanpa mempelajari sintaks spesifikasi. Ini juga merupakan jalur yang lebih cepat saat Anda memulai API baru dari awal dan ingin bergerak cepat melalui struktur tanpa khawatir tentang pemformatan.
Gunakan Mode Spec-First jika spesifikasi Anda sudah ada, atau seharusnya ada, di repositori Git di samping kode layanan Anda. Tim backend yang meninjau perubahan API dalam permintaan tarik, menjalankan linting spesifikasi di CI, atau menginginkan satu file YAML kanonis di seluruh alat akan merasa nyaman. Sinkronisasi dua arah berarti Apidog berhenti menjadi salinan kebenaran yang terpisah dan menjadi jendela ke file yang sama yang dimiliki repositori Anda.
Jalan tengah yang praktis: banyak tim merancang endpoint baru dalam Mode Design-First untuk kecepatan, lalu beralih ke Spec-First setelah API matang dan peninjauan Git menjadi prioritas. Mode-mode ini bukan produk saingan. Mereka adalah dua pandangan dari satu kontrak.
Cara beralih mode
Beralih hanya dengan satu tombol. Buka modul API di proyek Apidog Anda dan lihat di pojok kiri bawah, tempat pengalih mode berada. Balikkan, dan kontrak yang sama akan dirender dalam mode lain.
Beberapa hal yang perlu diingat saat Anda beralih:
- Spesifikasi yang mendasarinya dibagikan, sehingga endpoint, skema, dan contoh Anda tetap ada. Anda mengubah permukaan pengeditan, bukan membangun kembali API.
- Untuk menggunakan sinkronisasi Git Mode Spec-First, sambungkan repositori GitHub, GitLab, atau Azure DevOps Anda terlebih dahulu. Setelah terhubung, indikator sinkronisasi akan memberi tahu Anda apakah editan Anda telah di-commit dan di-push.
- Karena Mode Spec-First dalam versi beta, cobalah pada proyek di mana Anda dapat mengkonfirmasi perilaku sinkronisasi sebelum mengandalkannya untuk kontrak produksi.
Anda dapat bolak-balik sesuai perubahan kebutuhan Anda, jadi anggap pilihan ini sebagai default daripada komitmen.
FAQ
Apakah spec-first sama dengan contract-first?
Dalam praktiknya, ya. "Spec-first" dan "contract-first" keduanya berarti Anda membuat spesifikasi API sebelum implementasi, dan keduanya memperlakukan spesifikasi tersebut sebagai sumber kebenaran. Mode Spec-First Apidog adalah alur kerja contract-first di mana kontrak adalah file OpenAPI atau Swagger yang ditulis tangan dan disinkronkan ke Git.
Apakah Mode Spec-First berfungsi dengan GitLab dan Azure DevOps?
Ya. Mode Spec-First mendukung sinkronisasi Git dua arah dengan GitHub dan GitLab secara langsung. Azure DevOps berfungsi melalui Koneksi Git generik, jadi Anda juga dapat menyinkronkan file spesifikasi Anda ke repositori yang di-host Azure.
Bisakah saya beralih dari design-first ke spec-first tanpa kehilangan pekerjaan saya?
Ya. Kedua mode membaca dan menulis kontrak yang mendasarinya sama, sehingga endpoint, skema, dan contoh Anda tetap utuh saat Anda membalik tombol di kiri bawah modul API. Anda menukar editornya, bukan datanya.
Tidak yakin mana yang cocok untuk tim Anda? Buka modul API, coba tombol pengalih mode di kiri bawah, dan rancang endpoint berikutnya dengan kedua cara. Kontraknya sama; pilih permukaan yang sesuai dengan cara kerja tim Anda saat ini.