Kolaborasi Git untuk Pengujian dan Rekayasa API

Spesifikasi OpenAPI Anda adalah kontrak antara API Anda dan konsumennya. Namun di mana kontrak itu berada?

Terlalu sering, spesifikasi API tersimpan dalam alat yang terisolasi—diekspor sekali, terlupakan, dan jarang diperbarui saat implementasi berubah. Dokumentasi menyimpang. Koleksi pengujian tidak selaras. Peninjau menyetujui perubahan kode tanpa pernah melihat pembaruan spesifikasi yang sesuai.

Mode Spec-first mengubah model ini. File OpenAPI atau Swagger Anda menjadi sumber kebenaran, disimpan langsung di repositori Git Anda bersama dengan kode implementasi. Setiap perubahan spesifikasi mengalir melalui cabang, permintaan pull, dan proses peninjauan yang sama yang sudah Anda gunakan. Desain API, pengujian, dan dokumentasi semuanya tetap tersinkronisasi—secara otomatis.

Dalam tutorial ini, saya akan memandu Anda dalam menyiapkan proyek Spec-first di Apidog, mengedit spesifikasi bersama tim Anda, dan menjaga semuanya tetap sinkron dengan alur kerja Git Anda.

Apa itu Mode Spec-first?

Dalam proyek API tipikal, Anda membuat endpoint melalui formulir visual atau mengimpor spesifikasi yang ada sebagai titik awal. Alat tersebut menyimpan definisi API secara internal, dan integrasi Git (jika tersedia) adalah langkah ekspor.

Mode Spec-first berbeda. Ruang kerja utamanya berbasis file:

• openapi.yaml atau openapi.json berada di repo Anda
• Apidog mengurai file-file ini dan menghasilkan struktur API yang dapat dinavigasi
• Anda mengedit file secara langsung (atau melalui formulir yang didukung)
• Perubahan disinkronkan kembali ke Git secara otomatis

File spesifikasi selalu menjadi otoritas. Apidog membaca darinya, menulis kepadanya, dan menjaganya tetap sinkron dengan repositori Anda.

Prasyarat

Untuk mengikuti, Anda akan membutuhkan:

• Akun Apidog (tingkat gratis berfungsi)
• Sebuah repositori Git dengan file OpenAPI/Swagger, atau repo kosong untuk memulai dari awal
• Akses tulis ke repositori
• Keterbiasaan dasar dengan sintaks OpenAPI atau Swagger

Langkah 1: Buat Proyek Spec-first

Klik + Proyek Baru di Apidog dan pilih Mode Spec-first sebagai jenis proyek.

Selanjutnya, hubungkan penyedia Git Anda:

1. Pilih penyedia Anda (GitHub, GitLab, Azure DevOps, atau Bitbucket)
2. Pilih organisasi atau ruang kerja
3. Pilih repositori yang sudah ada atau buat yang baru
4. Pilih cabang utama untuk sinkronisasi

Apidog akan sinkron dengan cabang default repositori Anda. Jika namanya bukan main, Apidog beradaptasi secara otomatis.

Langkah 2: Konfigurasi Sinkronisasi Webhook (Direkomendasikan)

Selama penyiapan, Anda akan melihat opsi untuk menginstal webhook. Ini memungkinkan sinkronisasi otomatis setiap kali tim Anda mendorong ke repositori.

Catatan: Instalasi webhook biasanya memerlukan izin admin pada repositori. Jika Anda tidak memiliki akses admin, lewati langkah ini—Anda masih dapat menyinkronkan secara manual menggunakan Git Pull.

Manfaat Webhook:

• Tim mendorong perubahan → Apidog sinkron secara otomatis
• Tidak perlu penyegaran manual
• Semua orang melihat status spesifikasi terbaru

Jika Anda melewati penyiapan webhook pada awalnya, Anda dapat menambahkannya nanti dari Pengaturan Proyek > Git & Cabang.

Langkah 3: Jelajahi Ruang Kerja Spesifikasi

Setelah pembuatan, proyek Anda membuka ruang kerja Spesifikasi—pusat utama untuk pengeditan berbasis file dan operasi Git.

Tiga panel bekerja sama:

Klik endpoint di pohon struktur → Apidog menyoroti bagian yang sesuai dalam file sumber Anda. Navigasi dari tampilan API tingkat tinggi ke YAML tingkat rendah tanpa berpindah tab.

Langkah 4: Edit File Spesifikasi Anda

Tampilan Kode: Pengeditan Langsung

Untuk sebagian besar file—YAML, JSON, Markdown—gunakan tampilan Kode untuk mengedit teks mentah.

Pengeditan Anda tetap ada di file. Apidog tidak mengubah atau menyimpannya secara terpisah. File spesifikasi tetap menjadi satu-satunya sumber kebenaran.

Tampilan Formulir: Pengeditan Terstruktur

Untuk node OpenAPI yang didukung—endpoint, skema, definisi, dan ikhtisar API—beralih ke tampilan Formulir.

Tampilan formulir berguna ketika:

• Menambahkan endpoint dengan semua bidang yang diperlukan tanpa menghafal struktur YAML
• Mengedit skema secara visual
• Memperbarui definisi keamanan dan metadata API

Jika node tidak mendukung pengeditan formulir, Apidog akan tetap menempatkan Anda dalam tampilan kode.

Langkah 5: Validasi dan Pratinjau Secara Instan

Mode Spec-first mencakup validasi waktu nyata dan pratinjau dokumentasi—tidak memerlukan alat eksternal.

Periksa Masalah dengan Validasi

Klik Validasi di header editor. Sebuah panel menampilkan semua peringatan dan kesalahan dalam spesifikasi Anda saat ini.

Lencana menampilkan jumlah total masalah. Tangkap:

• Kesalahan sintaks
• Bidang wajib yang hilang
• Pelanggaran skema
• Masalah konvensi penamaan

Perbaiki masalah sebelum melakukan commit. Peninjau tim Anda tidak perlu menemukannya secara manual.

Pratinjau Dokumentasi Anda

Klik Pratinjau untuk melihat bagaimana spesifikasi Anda dirender sebagai dokumentasi API.

Untuk endpoint, pratinjau mencakup dua tab:

Untuk skema dan definisi, pratinjau menunjukkan tampilan dokumentasi yang dirender.

Validasi dan Pratinjau berbagi panel samping yang sama. Membuka salah satu secara otomatis menutup yang lain.

Langkah 6: Ambil Pembaruan dari Tim Anda

Ketika kolaborator mendorong perubahan ke repositori Anda, masukkan ke Apidog:

1. Buka ruang kerja Spesifikasi
2. Klik nama cabang saat ini di bilah sisi
3. Pilih Git Pull

Jika sinkronisasi webhook aktif, Apidog akan menarik secara otomatis pada peristiwa dorongan repositori—tidak diperlukan langkah manual.

Langkah 7: Commit dan Push Perubahan Anda

Setelah mengedit file di Apidog, kirim pembaruan Anda kembali ke Git:

1. Buat perubahan di ruang kerja Spesifikasi
2. Klik Perubahan di bilah sisi untuk melihat file yang dimodifikasi, ditambahkan, diganti namanya, dan dihapus
3. Klik Commit & Push
4. Pilih file mana yang akan disertakan
5. Tulis pesan commit
6. Klik Push

Pembaruan spesifikasi Anda sekarang muncul dalam alur kerja permintaan pull yang sama dengan perubahan kode Anda. Rekan satu tim dapat meninjau, berkomentar, dan menyetujui—baik implementasi maupun kontrak API di satu tempat.

Tip: Gunakan Buang semua perubahan jika Anda ingin membatalkan pengeditan lokal sebelum melakukan push.

Langkah 8: Bekerja dengan Cabang

Mode Spec-first mendukung kolaborasi berbasis cabang penuh. Apidog memetakan cabang Git ke cabang proyek, memungkinkan Anda beralih antar versi spesifikasi.

Operasi Cabang Umum

Manajemen cabang bekerja dengan cara yang sama seperti yang Anda harapkan dari Git—cabang fitur, rilis, dan pengembangan paralel semuanya sinkron dengan benar.

Langkah 9: Integrasi dengan CI/CD

Karena spesifikasi Anda berada di Git, spesifikasi tersebut secara alami cocok dengan pipeline otomatisasi:

• Lint spesifikasi di setiap PR menggunakan validasi Apidog atau alat seperti Spectral
• Buat dokumentasi secara otomatis ketika spesifikasi digabungkan ke main
• Jalankan pengujian API yang dipicu oleh perubahan spesifikasi
• Sinkronkan ke sistem hilir—gateway API, server mock, generator SDK

Contoh alur kerja GitHub Actions:

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

Spesifikasi API Anda kini melewati gerbang kualitas yang sama dengan kode aplikasi Anda.

Alternatif: Proyek Berbasis Penyimpanan

Jika Anda belum siap untuk menghubungkan repositori Git eksternal, Apidog menawarkan proyek Spec-first berbasis penyimpanan.

Proyek-proyek ini menggunakan penyimpanan internal Apidog tetapi masih menyediakan:

• Pengeditan berbasis file
• Validasi dan pratinjau
• Manajemen cabang

Label UI sedikit disesuaikan:

• Git Pull menjadi Sinkronkan
• Commit & Push menjadi Simpan

Migrasi ke Git eksternal kapan pun tim Anda siap.

Ringkasan

Dengan Mode Spec-first, alur kerja API Anda menjadi:

Mode Spec-first menjadikan file OpenAPI sebagai kontrak yang seharusnya—terversi, ditinjau, dan selalu selaras dengan kode Anda.

Siap mencoba? Buat proyek Spec-first di Apidog dan hubungkan repositori pertama Anda.