Jika spesifikasi API Anda ada di Apidog tetapi sumber kebenaran Anda ada di Git, Anda pasti ingin keduanya selaras. Integrasi Git Apidog menjembatani kesenjangan tersebut. Ini memungkinkan Anda menghubungkan repositori GitHub, GitLab, atau Azure DevOps ke proyek Anda, mendorong spesifikasi OpenAPI Anda ke kontrol versi, dan menarik perubahan repo kembali ke Apidog. Anda mendapatkan jejak audit yang bersih, tinjauan kode pada perubahan spesifikasi, dan cadangan yang tetap aman dari apa pun yang terjadi di dalam aplikasi.
Ini adalah referensi yang luas. Ini mencakup setiap penyedia yang didukung Apidog, kedua cara produk berkomunikasi dengan Git, dan keputusan praktis yang akan Anda hadapi: repo mana, cabang mana, siapa yang dapat mendorong, dan apa yang harus dilakukan ketika terjadi masalah. Jika Anda hanya membutuhkan panduan GitHub yang terfokus, bacalah panduan khusus tentang cara menyinkronkan spesifikasi OpenAPI Anda ke GitHub. Di sini, kita akan membahasnya lebih luas.
Apa yang dilakukan integrasi Git Apidog
Apidog berkomunikasi dengan Git dalam dua cara berbeda. Keduanya memecahkan masalah yang berbeda, dan Anda dapat menggunakan salah satunya, yang lain, atau keduanya. Mencampuradukkan keduanya adalah sumber kebingungan yang paling umum, jadi mari kita pisahkan terlebih dahulu.
Kemampuan pertama adalah sinkronisasi dua arah melalui Mode Spec-First. Anda mengedit dokumen OpenAPI Anda sebagai YAML atau JSON di dalam editor bergaya IDE Apidog, melakukan perubahan Anda, dan mendorongnya ke cabang yang terhubung. Ketika orang lain memperbarui spesifikasi di repo, Anda menarik perubahan tersebut kembali ke Apidog. Ini adalah perjalanan pulang pergi yang nyata: pengeditan mengalir keluar ke Git, dan perubahan repo mengalir kembali.
Kemampuan kedua adalah pencadangan Git otomatis untuk spesifikasi API. Di sini, Apidog mengekspor file OpenAPI/Swagger setiap modul dan mendorongnya ke repositori sesuai jadwal. Ini bersifat satu arah dan tanpa campur tangan. Anda mengkonfigurasinya sekali, dan sistem menyimpan salinan spesifikasi Anda yang telah diberi versi di Git tanpa Anda harus melakukan apa pun. Ini adalah jaring pengaman, bukan alur kerja pengeditan.
| Kemampuan | Arah | Pemicu | Terbaik untuk |
|---|---|---|---|
| Sinkronisasi Mode Spec-First | Dua arah (dorong dan tarik) | Commit/dorong manual, tarik manual | Tim yang memperlakukan spesifikasi sebagai kode dan menginginkan tinjauan pada setiap perubahan |
| Pencadangan Git otomatis | Satu arah (Apidog → Git) | Terjadwal, di luar jam sibuk | Siapa pun yang menginginkan cadangan yang telah diberi versi tanpa mengubah cara kerja mereka |
Ingatlah perbedaan ini untuk sisa artikel. Ketika kami mengatakan "sinkronisasi", kami mengacu pada alur dua arah Mode Spec-First. Ketika kami mengatakan "cadangan", kami mengacu pada ekspor satu arah yang terjadwal.
Penyedia Git yang didukung
Apidog mendukung tiga penyedia yang sebagian besar tim sudah gunakan. GitHub dan GitLab terhubung langsung melalui alur otorisasi bawaan mereka. Azure DevOps terhubung melalui Koneksi Git generik, yang berfungsi dengan host Git mana pun yang menggunakan otentikasi HTTPS standar.
| Penyedia | Metode otentikasi | Catatan |
|---|---|---|
| GitHub | Otorisasi OAuth (login GitHub) | Berfungsi dengan repo pribadi dan organisasi. Repo organisasi mungkin memerlukan admin untuk menyetujui koneksi. |
| GitLab | Otorisasi OAuth (login GitLab) | Mendukung gitlab.com dan instansi yang dikelola sendiri yang dapat dijangkau dari Apidog. |
| Azure DevOps | Koneksi Git Generik (HTTPS + token) | Terhubung melalui URL HTTPS repo dan token akses pribadi (PAT) dengan cakupan repo. |
Koneksi Git generik adalah jalan keluar. Jika host Anda bukan GitHub atau GitLab secara nama, tetapi ia berbicara Git standar melalui HTTPS dengan otentikasi token, koneksi generik biasanya menanganinya. Azure DevOps adalah kasus utamanya, tetapi jalur yang sama mencakup pengaturan yang di-hosting sendiri yang mengekspos URL klon HTTPS.
Menghubungkan penyedia Git Anda
Langkah koneksi adalah tempat Anda memberikan Apidog akses yang diperlukan untuk membaca dan menulis repo Anda. Mekanikanya sedikit berbeda untuk setiap penyedia, tetapi bentuknya sama: otorisasi, pilih repo, pilih cabang.
Untuk GitHub, Anda mengotorisasi melalui layar OAuth GitHub. Apidog meminta akses repositori agar dapat membaca spesifikasi dan mendorong komit. Jika repo tersebut milik organisasi, GitHub mungkin mengarahkan permintaan melalui administrator organisasi yang menyetujui akses pihak ketiga. Repo pribadi akan segera diotorisasi di bawah akun Anda sendiri.
Untuk GitLab, alurnya mencerminkan GitHub. Anda masuk melalui layar OAuth GitLab dan memberikan akses repositori. GitLab yang dikelola sendiri berfungsi selama Apidog dapat menjangkau instansi tersebut melalui jaringan.
Untuk Azure DevOps, Anda menggunakan Koneksi Git generik. Alih-alih jabat tangan OAuth, Anda memberikan URL klon HTTPS repositori dan token akses pribadi (PAT). Buat PAT di Azure DevOps dengan izin untuk membaca dan menulis kode, lalu tempelkan ke Apidog. Token adalah kredensial yang memungkinkan Apidog mendorong komit, jadi lingkupkanlah ke repo yang benar-benar dibutuhkan.
Beberapa catatan izin yang menghemat waktu:
- Repo organisasi vs pribadi. Repositori organisasi sering kali memerlukan admin untuk menyetujui integrasi satu kali. Jika otorisasi Anda tampaknya berhasil tetapi Apidog tidak dapat melihat repo, persetujuan admin biasanya hilang.
- Lingkupkan token dengan ketat. Untuk Azure DevOps dan koneksi generik apa pun, berikan PAT izin baca/tulis pada kode hanya untuk proyek target. Hindari token akun penuh.
- Repo pribadi tidak masalah. Apidog bekerja dengan repositori pribadi. Akses berasal dari otorisasi atau token yang Anda berikan, bukan dari visibilitas publik.
Setelah penyedia terhubung, Anda membuat proyek Apidog dari repositori ditambah sebuah cabang, biasanya main. Pasangan itulah yang mengikat spesifikasi Anda ke tempat tertentu dalam kontrol versi. Jika Anda baru dalam praktik yang lebih luas, panduan kami tentang kontrol versi OpenAPI dengan Git mencakup konvensi yang layak diadopsi sebelum Anda menyambungkan semuanya.
Sinkronisasi dua arah dengan Mode Spec-First
Mode Spec-First adalah tempat sinkronisasi dua arah berada. Ini mengubah Apidog menjadi editor spesifikasi yang melakukan komit ke Git seperti kode lainnya. Anda dapat membaca referensi lengkap di dokumentasi resmi Apidog; berikut adalah cara perjalanan pulang pergi bekerja dalam praktik.
Anda mengedit dokumen OpenAPI secara langsung sebagai YAML atau JSON. Editornya bergaya IDE: ia memberi Anda penyorotan sintaksis, validasi langsung, dan pelengkapan otomatis, sehingga $ref yang salah format atau bidang wajib yang hilang akan muncul saat Anda mengetik daripada setelah Anda mendorong. Saat Anda mengedit, bilah sisi kiri secara otomatis mengurai dokumen menjadi kerangka, jalur, operasi, dan skema, sehingga Anda dapat menavigasi spesifikasi besar tanpa menggulir teks mentah.
Pengeditan tipikal terlihat seperti ini. Katakanlah Anda menambahkan sebuah endpoint:
paths:
/v1/orders/{orderId}:
get:
operationId: getOrder
summary: Retrieve a single order
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: The requested order
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
Ketika Anda menyimpan perubahan itu, Apidog menahannya sebagai edit lokal. Anda kemudian melakukan commit dengan pesan dan mendorong ke cabang yang terhubung, persis seperti yang Anda lakukan dengan alur kerja Git lainnya. Setelah push berhasil, indikator sinkronisasi akan menampilkan "Disinkronkan barusan" sebagai konfirmasi Anda bahwa Apidog dan cabang memiliki konten yang sama.
Arah penarikan sama pentingnya. Ketika rekan satu tim mengedit spesifikasi di repo dan mendorongnya, Anda menarik perubahan tersebut ke Apidog untuk memperbarui salinan lokal Anda. Inilah yang membuat integrasi benar-benar dua arah: repo bukan hanya target cadangan, melainkan rekan.
Jika Anda melakukan pengeditan yang tidak ingin Anda simpan, Anda dapat membuang pengeditan yang belum didorong sebelum melakukan commit. Itu akan mengembalikan salinan kerja Anda agar sesuai dengan status terakhir yang disinkronkan, yang berguna ketika Anda sedang bereksperimen dan memutuskan bahwa perubahan tersebut tidak layak disimpan.
Ritme commit-dan-push ini adalah inti dari alur kerja API asli Git; perubahan spesifikasi melalui mekanisme tinjauan, riwayat, dan pengembalian yang sama dengan bagian lain dari basis kode Anda. Peninjau mengomentari perbedaan YAML dalam permintaan tarik, persetujuan mengunci penggabungan, dan riwayat desain API Anda terbaca seperti riwayat kode Anda.
Pencadangan Git otomatis untuk spesifikasi API
Kemampuan pencadangan adalah separuh yang lebih tenang dari integrasi Git Apidog, dan itu hampir tidak meminta apa pun dari Anda setelah pengaturan. Anda mengarahkan modul ke repositori, dan Apidog menangani sisanya.
Berikut adalah mekanismenya. Apidog dapat mencadangkan file OpenAPI/Swagger untuk setiap modul ke repositori Git, GitHub, GitLab, dan Azure DevOps semuanya didukung. Setelah Anda menyimpan konfigurasi pencadangan, sistem secara otomatis mendorong file Spesifikasi OpenAPI modul ke repo yang ditentukan. Dorongan terjadi selama jendela di luar jam sibuk yang diacak pada malam hari, yang membuatnya tidak mengganggu jam kerja Anda dan menyebarkan beban.
Yang disimpan adalah dokumen OpenAPI/Swagger yang diekspor untuk modul tersebut, sebuah snapshot dari kontrak API sebagaimana adanya. Karena setiap push adalah commit, Anda mengumpulkan riwayat versi di Git. Anda dapat membedakan kontrak minggu lalu dengan hari ini, melihat dengan tepat kapan suatu bidang berubah, dan mengembalikan versi sebelumnya langsung dari repo jika sewaktu-waktu Anda membutuhkannya.
Alur pencadangan dirancang satu arah. Apidog menulis ke repo; ia tidak membaca perubahan kembali darinya. Jika Anda ingin pengeditan repo mengalir ke Apidog, itu adalah tugas Mode Spec-First, bukan cadangan. Gunakan cadangan ketika tujuan Anda adalah ketahanan dan riwayat tanpa mengubah cara tim Anda bekerja sehari-hari.
Memilih struktur cabang dan repo
Keputusan struktural yang Anda buat di awal akan membentuk kelancaran integrasi nantinya. Dua pertanyaan mendominasi: cabang mana, dan berapa banyak repo.
Pilihan cabang. Sebagian besar tim melakukan sinkronisasi ke main untuk spesifikasi kanonik dan menggunakan cabang fitur untuk desain yang sedang berlangsung. Mengarahkan Apidog ke cabang fitur memungkinkan Anda berulang-ulang pada perubahan spesifikasi secara terpisah, membuka permintaan tarik (pull request), dan menggabungkan (merge) setelah tinjauan selesai; desain API Anda mengikuti model percabangan yang sama dengan kode Anda. Mengarahkan Apidog ke main secara langsung lebih sederhana tetapi melewati gerbang tinjauan, jadi simpan untuk tim kecil atau perubahan berisiko rendah.
Satu repo atau banyak. Tidak ada jawaban tunggal yang benar, tetapi pertukarannya jelas:
- Satu repo per API menjaga riwayat setiap spesifikasi tetap bersih dan kontrol aksesnya sempit. Ini sangat cocok ketika tim yang berbeda memiliki API yang berbeda.
- Monorepo untuk semua spesifikasi memusatkan segalanya dan menyederhanakan pencarian dan peninjauan lintas-API. Ini berfungsi dengan baik ketika satu tim platform memiliki seluruh permukaan API. Cukup pertahankan tata letak direktori yang dapat diprediksi, satu folder per modul, agar cadangan dan sinkronisasi tidak bertabrakan.
Jika Anda menjalankan monorepo, berikan setiap modul jalurnya sendiri. Itu menjaga cadangan otomatis tetap rapi dan membuat perbedaan spesifikasi mudah dibaca dalam tinjauan.
Izin dan akses tim
Integrasi Git menyentuh kredensial, jadi penting untuk berhati-hati dalam menentukan siapa yang bisa melakukan apa. Izin berada di dua tempat: di dalam Apidog, dan di dalam penyedia Git Anda.
Di dalam Apidog, izin tim dikonfigurasi selama penyiapan proyek. Di situlah Anda memutuskan siapa yang dapat menyinkronkan dan mendorong ke repo yang terhubung. Batasi hak dorong hanya untuk orang yang memiliki spesifikasi, dan biarkan orang lain membaca. Ini mencegah dorongan yang tidak disengaja dari kontributor yang hanya menjelajahi desain API.
Di dalam penyedia Git Anda, kredensial itu penting. Untuk GitHub dan GitLab, otorisasi OAuth membawa akses dari pengguna yang memberikannya. Untuk Azure DevOps dan koneksi generik, token akses pribadi (PAT) adalah kredensial, perlakukan seperti rahasia. Jangan menempelkan token ke dokumen bersama, lingkupkan hanya ke repo target, dan rotasi sesuai frekuensi Anda merotasi rahasia lainnya. Jika seseorang meninggalkan tim, cabut token mereka dan otorisasi ulang di bawah akun yang masih aktif.
Prinsipnya sederhana: integrasi hanya seaman token terlemah di baliknya. Pertahankan cakupan yang sempit dan kepemilikan yang jelas.
Menangani konflik penggabungan dan pergeseran
Karena Apidog melakukan commit riwayat Git sungguhan, ia mewarisi model konflik Git, dan alat Git untuk menyelesaikannya. Konflik terjadi ketika dua orang mengubah bagian spesifikasi yang sama sebelum melakukan sinkronisasi.
Bayangkan skenarionya. Anda mengedit skema Order di Apidog dan mendorongnya. Rekan satu tim mengedit skema yang sama di sisi repo dan mendorongnya terlebih dahulu. Ketika Anda mencoba mendamaikan, Git menandai konflik pada YAML, karena kedua belah pihak mengubah baris yang tumpang tindih. Ini bukan masalah Apidog; ini adalah konflik penggabungan Git normal pada file YAML, dan Anda menyelesaikannya dengan cara normal.
Untuk menghindari konflik, tarik sebelum Anda mendorong. Membawa status repo terbaru ke Apidog sebelum melakukan perubahan Anda sendiri menjaga salinan kerja Anda tetap terkini dan mempersempit jendela di mana dua pengeditan bertabrakan. Ketika konflik terjadi, selesaikan pada YAML dengan cara yang sama Anda akan menyelesaikan konflik penggabungan lainnya: pilih baris yang benar, jaga dokumen tetap valid, dan sinkronkan ulang. Validasi langsung editor membantu di sini, penggabungan yang gagal yang merusak struktur OpenAPI akan segera terlihat daripada setelah Anda mendorong.
Drift, di mana Apidog dan repo diam-diam menyimpang, adalah versi lambat dari masalah yang sama. Indikator "Disinkronkan barusan" adalah peringatan awal Anda. Jika tidak menampilkan disinkronkan, ada sesuatu yang belum didorong atau ditarik. Anggap itu sebagai dorongan untuk mendamaikan sebelum kesenjangan melebar.
Pemecahan Masalah
Sebagian besar masalah integrasi bermuara pada otentikasi, pemilihan cabang, atau sinkronisasi yang terganggu. Kerjakan tabel di bawah ini sebelum berasumsi ada sesuatu yang lebih dalam yang salah.
| Gejala | Kemungkinan penyebab | Perbaikan |
|---|---|---|
| Otorisasi gagal atau repo tidak muncul | Organisasi belum menyetujui akses pihak ketiga, atau token tidak memiliki cakupan | Minta admin organisasi menyetujui aplikasi GitHub/GitLab; untuk Azure DevOps, terbitkan ulang PAT dengan cakupan kode baca/tulis |
| Dorongan ditolak | Token dicabut atau kedaluwarsa, atau tidak ada izin tulis | Otorisasi ulang penyedia; untuk koneksi generik, buat PAT baru dan perbarui di Apidog |
| Perubahan didorong tetapi tidak terlihat | Mengarah ke cabang yang salah | Konfirmasi cabang yang terhubung cocok dengan tempat yang Anda harapkan komit; alihkan cabang di pengaturan proyek |
| Sinkronisasi macet atau "Disinkronkan barusan" tidak pernah muncul | Pengeditan lokal yang belum didorong, atau perlu ditarik | Lakukan komit dan dorong pengeditan yang tertunda; jika rekan tim mendorong, tarik terlebih dahulu, lalu sinkronkan ulang |
| Konflik penggabungan pada spesifikasi | Dua pengeditan pada baris yang sama | Selesaikan konflik YAML secara normal, jaga dokumen tetap valid, sinkronkan ulang |
| Pencadangan tidak berjalan | Dorongan terjadwal belum mencapai jendela di luar jam sibuk | Pencadangan didorong selama jendela malam yang diacak; tunggu siklus berikutnya atau verifikasi konfigurasi repo/cabang pencadangan |
| Pengeditan yang tidak Anda maksudkan untuk disimpan | Perubahan eksperimental sebelum komit | Gunakan "buang pengeditan yang belum didorong" untuk kembali ke status terakhir yang disinkronkan |
Jika otorisasi adalah tema yang berulang, dan biasanya memang begitu, mulailah dengan mengkonfirmasi bahwa kredensial aktif dan dicakup dengan benar. Token yang dicabut atau persetujuan organisasi yang hilang menjelaskan sebagian besar laporan "tiba-tiba berhenti berfungsi".
FAQ
Apakah sinkronisasi satu arah atau dua arah?
Tergantung pada kemampuan mana yang Anda gunakan. Mode Spec-First bersifat dua arah: Anda mendorong pengeditan ke Git dan menarik perubahan repo kembali ke Apidog. Pencadangan otomatis bersifat satu arah: Apidog mengekspor spesifikasi setiap modul ke repo sesuai jadwal dan tidak membaca perubahan kembali.
Di mana spesifikasi saya disimpan?
Di repositori Git yang Anda sambungkan. Untuk Mode Spec-First, dokumen OpenAPI Anda berada di cabang yang Anda dorong. Untuk pencadangan otomatis, file OpenAPI/Swagger yang diekspor setiap modul dikomit ke repo yang Anda konfigurasikan. Dalam kedua kasus, Git menyimpan salinan yang diberi versi, dan Anda memiliki kendali penuh atas repositori.
Cabang mana yang harus saya sinkronkan?
Gunakan main untuk spesifikasi kanonik dan cabang fitur untuk perubahan yang sedang berlangsung. Sinkronisasi ke cabang fitur memungkinkan perubahan spesifikasi melalui permintaan tarik (pull request) dan peninjauan sebelum digabungkan (merge), yang mencerminkan bagaimana kode Anda sudah bergerak melalui Git.
Apa yang terjadi jika token saya dicabut?
Dorongan mulai gagal karena Apidog tidak lagi memiliki akses tulis. Otorisasi ulang penyedia, atau, untuk Azure DevOps dan koneksi generik, hasilkan token akses pribadi (PAT) baru dan perbarui di Apidog. Setelah kredensial dipulihkan, sinkronisasi dan pencadangan akan dilanjutkan secara normal.
Kesimpulan
Integrasi Git Apidog memberi Anda dua alat pelengkap: sinkronisasi dua arah melalui Mode Spec-First untuk tim yang memperlakukan spesifikasi sebagai kode, dan pencadangan otomatis per-modul untuk siapa saja yang hanya menginginkan jaring pengaman berversi. Keduanya berfungsi di GitHub, GitLab, dan Azure DevOps, sehingga Anda dapat menghubungkan penyedia yang sudah Anda gunakan daripada mengadopsi yang baru.
Pilih kemampuan yang sesuai dengan tujuan Anda. Jika Anda menginginkan tinjauan dan riwayat pada setiap perubahan spesifikasi, atur Mode Spec-First dan adopsi ritme commit-dan-push. Jika Anda menginginkan ketahanan tanpa mengubah alur kerja Anda, aktifkan cadangan dan biarkan dorongan malam menanganinya. Banyak tim menjalankan keduanya. Saat Anda siap menyambungkannya, sambungkan penyedia Anda, arahkan proyek ke repo dan cabang, dan biarkan spesifikasi API Anda berada di tempat pekerjaan Anda yang lain sudah ada.