Saya Menghabiskan Pagi dengan Mode Spec-First Apidog: Desainer Visual Bukan Lagi Satu-satunya Pemegang Kendali

Ada dua pola kerja yang sering muncul di tim API: menulis spesifikasi OpenAPI langsung di repo, atau mendesain endpoint lewat UI lalu mengekspor spesifikasi saat dibutuhkan.

Coba Apidog hari ini

Saya pernah memakai keduanya. Workflow berbasis Git terasa lebih lambat di awal, tetapi lebih stabil setelah proyek berjalan lama. Workflow visual lebih cepat untuk mulai, tetapi sering menimbulkan selisih antara “spesifikasi di tool” dan “spesifikasi di repo”.

Sampai baru-baru ini, Apidog lebih kuat di workflow visual. Designer-nya nyaman, tetapi round-trip YAML masih perlu disiplin review. Lalu pada pertengahan April, Apidog menambahkan Mode Spesifikasi-Pertama / Spec-First Mode Beta di dialog proyek baru.

Saya mencobanya dengan spesifikasi OpenAPI dari proyek sampingan. Artikel ini merangkum cara setup, perilaku Git sync, dan kapan mode ini cocok dipakai.

Apa yang Berubah di Mode Spesifikasi-Pertama

Apidog sekarang punya dua mode proyek yang cara kerjanya berbeda.

Mode default adalah workflow visual: buat proyek, isi form endpoint, lalu Apidog menghasilkan spesifikasi OpenAPI di belakang layar. Ini cocok untuk tim yang belum terbiasa mengedit YAML atau JSON secara langsung.

Mode Spesifikasi-Pertama membalik modelnya:

• File OpenAPI .yaml atau .json menjadi sumber kebenaran.
• File tersebut disinkronkan dua arah dengan repository Git.
• Editor Apidog bekerja seperti code editor, bukan form builder.
• Sidebar endpoint dibuat dari spesifikasi secara real time.
• UI menjadi tampilan dan navigasi untuk file, bukan tempat utama menyimpan state.

Dengan kata lain, artefak utama tetap file di repo.

Hal paling berguna di sini adalah panel “Penguraian Direktori Waktu Nyata”. YAML tidak sulit, tetapi struktur API sering tersembunyi saat file makin panjang. Sidebar Apidog menyelesaikan masalah itu tanpa memaksa Anda keluar dari file.

Anda tetap menulis OpenAPI, tetapi mendapat navigasi visual.

Setup Mode Spesifikasi-Pertama

Berikut langkah yang saya pakai. Totalnya kurang dari sepuluh menit, sebagian besar untuk otorisasi Git.

1. Buat proyek dengan mode yang benar

Di layar proyek:

+ Proyek Baru → Umum → Mode Spesifikasi-Pertama

Perhatikan pemilih mode. Mode Umum ditandai “Direkomendasikan”, jadi ubin Mode Spesifikasi-Pertama mudah terlewat jika Anda terbiasa membuat proyek default.

2. Hubungkan repository Git

Di bagian Hubungkan dengan Repositori Git, otorisasi provider Git Anda.

Saya memakai GitHub, tetapi dokumentasi juga mencakup provider lain. Setelah otorisasi, pilih:

• Organisasi
• Repositori
• Cabang utama

Apidog akan memakai branch tersebut sebagai working copy untuk file spesifikasi.

3. Konfigurasi proyek

Isi:

• Nama Proyek
• Izin tim
• Repository dan branch target

Lalu klik Buat.

Sinkronisasi awal akan menarik file .yaml dan .json yang sudah ada di repo ke workspace Apidog.

4. Edit spesifikasi seperti file biasa

Buka salah satu file OpenAPI.

Anda akan mendapat:

• syntax highlighting
• autocompletion berbasis skema OpenAPI
• sidebar endpoint yang diperbarui saat mengetik
• navigasi langsung ke route tertentu

Contoh struktur yang akan langsung terbaca oleh sidebar:

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0

paths:
  /store/token:
    post:
      summary: Generate store token
      responses:
        "200":
          description: Token generated

Saat route baru ditambahkan di paths, kerangka endpoint di sidebar ikut berubah. Klik endpoint di sidebar akan membawa Anda ke baris terkait.

5. Commit dan push dari Apidog

Di kanan atas, klik Commit & Push.

Dialog commit berisi:

• daftar file di bagian Perubahan
• kolom Pesan Commit
• tombol Push
• tombol Buang semua perubahan

Tidak ada step staging terpisah. File yang masuk daftar perubahan akan ikut commit, kecuali Anda menghapus centangnya.

6. Pantau indikator sinkronisasi

Di pojok kiri bawah ada indikator seperti Baru saja disinkronkan.

Gunakan indikator ini untuk memastikan status kerja Anda:

• perubahan lokal sudah dipush
• remote punya perubahan baru
• workspace tertinggal dari repo
• workspace dan repo sudah sinkron

Dalam praktiknya, indikator ini lebih berguna daripada menunggu modal atau notifikasi. Jika statusnya hijau, workspace dan repo berada di state yang sama.

Perilaku yang Perlu Diketahui

Ada tiga hal yang paling terasa saat saya mencobanya.

1. Sidebar endpoint diperbarui cepat

Beberapa editor OpenAPI baru memperbarui struktur setelah file disimpan. Di Apidog, sidebar berubah saat saya mengetik.

Ini penting karena sidebar bisa dipakai sebagai alat navigasi, bukan sekadar laporan status setelah edit selesai.

2. Git sync benar-benar dua arah

Saya mencoba mengedit file yang sama dari local clone lalu push lewat terminal saat Apidog masih terbuka.

Hasilnya:

1. Apidog mendeteksi remote berubah.
2. Indikator sinkronisasi menunjukkan workspace tertinggal.
3. Satu klik menarik perubahan ke editor.

Tidak ada dialog merge dalam percobaan tersebut. Untuk tim campuran, ini berarti satu developer bisa tetap memakai Vim atau VS Code, sementara yang lain memakai Apidog. File di repo tetap menjadi sumber kebenaran bersama.

3. Tidak bisa pindah ke visual designer di proyek yang sama

Ini keputusan desain yang perlu dipahami sejak awal.

Jika proyek dibuat dengan Mode Spesifikasi-Pertama, proyek itu tetap spec-first. Anda tidak bisa mengganti proyek yang sama menjadi mode visual karena model data di bawahnya berbeda.

Jika tim Anda perlu memakai dua pendekatan, workflow yang lebih aman adalah:

1. Simpan spesifikasi OpenAPI di repository.
2. Buat proyek Spec-First yang menunjuk ke repo tersebut.
3. Untuk pengguna visual, buat proyek terpisah yang mengimpor spesifikasi dari sumber yang sama.

Ini belum semulus satu proyek dengan dua mode, tetapi tetap bisa dijalankan.

Kapan Mode Ini Cocok

Mode Spesifikasi-Pertama cocok jika tim Anda:

• sudah menulis OpenAPI secara manual
• menyimpan spesifikasi di Git
• menjalankan lint seperti spectral lint di CI
• menghasilkan SDK client dari spesifikasi
• ingin menghindari perbedaan antara “spesifikasi di tool” dan “spesifikasi di repo”
• punya developer yang tetap ingin mengedit YAML dari editor lokal

Contoh workflow CI yang umum:

spectral lint openapi.yaml

Atau jika spesifikasi dipakai untuk generate client:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated/client

Dalam workflow seperti ini, file OpenAPI harus menjadi sumber kebenaran. Mode Spec-First membantu karena Apidog tidak mencoba menggantikan repo, tetapi bekerja di atasnya.

Kapan Sebaiknya Tetap Pakai Mode Default

Mode ini kurang cocok jika:

• tim belum pernah menyentuh OpenAPI
• kontributor lebih nyaman dengan form visual
• tujuan utama adalah onboarding cepat
• sebagian besar anggota tim bukan spesialis API
• Anda perlu visual designer dan spec-first editor dalam proyek yang sama

Untuk tim seperti itu, mode default Apidog masih lebih tepat. Mode Spesifikasi-Pertama menukar kemudahan onboarding dengan kontrol yang lebih presisi terhadap file spesifikasi.

Kesimpulan

Mode Spesifikasi-Pertama membuat Apidog lebih cocok untuk workflow berbasis Git.

Poin utamanya:

• OpenAPI tetap berupa file di repo.
• Editor Apidog bekerja langsung terhadap file tersebut.
• Sidebar hanya menjadi tampilan struktur.
• Git sync menjadi jembatan antara Apidog dan workflow developer.

Jika selama ini Anda mengelola spesifikasi dengan proses ekspor manual seperti:

make export

lalu tetap harus memeriksa apakah file di repo sesuai dengan yang ada di tool, mode ini layak dicoba.

Versi beta sudah tersedia di dialog Proyek Baru. Buat proyek dengan Mode Spesifikasi-Pertama, hubungkan ke repo yang sudah Anda percaya, lalu lakukan commit pertama dari Apidog. Setup awalnya singkat; keputusan untuk mempertahankannya biasanya baru terlihat setelah beberapa hari dipakai dalam workflow tim.