TL;DR
Konflik sinkronisasi SwaggerHub terjadi ketika pengeditan bersamaan atau integrasi Git menciptakan versi spesifikasi yang saling bertentangan. Resolusi melibatkan identifikasi versi yang bertentangan, menggabungkan perubahan secara manual, dan melakukan `recommit`. Pencegahan lebih baik daripada resolusi — kepemilikan yang jelas, disiplin cabang, dan konvensi penguncian mengurangi sebagian besar konflik sebelum terjadi. Model `branching` Apidog mengurangi konflik pengeditan bersamaan secara desain.
Pendahuluan
Fitur pengeditan kolaboratif SwaggerHub sangat berguna. Beberapa anggota tim dapat mengerjakan definisi API yang sama, perubahan terlihat hampir secara real time, dan integrasi Git memungkinkan tim menjaga spesifikasi tetap sinkron dengan repositori sumber mereka.
Namun kolaborasi menimbulkan konflik. Dua insinyur mengedit titik akhir yang sama secara bersamaan. Sebuah spesifikasi diperbarui di SwaggerHub dan secara terpisah di GitHub, dan proses sinkronisasi menghadapi versi yang berbeda. Sebuah Domain diperbarui saat sebuah API sedang dalam tinjauan. Konflik-konflik ini dapat dikelola, tetapi mengganggu ketika terjadi secara tak terduga dan tim tidak memiliki proses resolusi yang jelas.
Panduan ini menjelaskan jenis-jenis konflik yang terjadi di SwaggerHub, cara mengatasi setiap jenisnya, dan cara mencegahnya dengan disiplin alur kerja yang lebih baik. Bagian terakhir membahas bagaimana pendekatan Apidog menangani masalah kelas yang sama.
Jenis-jenis konflik sinkronisasi di SwaggerHub
1. Konflik pengeditan bersamaan. SwaggerHub memungkinkan banyak pengguna mengedit definisi API pada saat yang sama. Ketika dua pengguna mengedit bagian spesifikasi yang sama secara bersamaan, penyimpanan terakhir yang akan berlaku. Tidak ada penggabungan — penyimpanan kedua menimpa perubahan pengguna pertama. Ini secara teknis bukan "konflik" dalam artian Git (tidak ada status error), tetapi menyebabkan kehilangan data jika tim tidak berhati-hati.
2. Konflik sinkronisasi SwaggerHub-ke-Git. SwaggerHub terintegrasi dengan GitHub, GitLab, dan Bitbucket. Ketika sebuah spesifikasi disimpan di SwaggerHub, ia dapat secara otomatis mendorong (`auto-push`) ke repositori yang dikonfigurasi. Ketika sebuah file spesifikasi dikomit langsung ke repositori, ia dapat disinkronkan kembali ke SwaggerHub. Jika keduanya terjadi secara independen, Anda akan mendapatkan versi yang saling bertentangan yang tidak dapat direkonsiliasi secara otomatis oleh proses sinkronisasi SwaggerHub.
3. Konflik percabangan versi API. Ketika Anda membuat cabang (`fork`) versi API di SwaggerHub untuk membuat cabang kerja baru, kemudian mencoba menggabungkan perubahan kembali, perbedaan antara cabang (`fork`) dan versi asli dapat menciptakan konflik yang memerlukan resolusi manual.
4. Konflik ketidakcocokan versi Domain. Jika sebuah API mereferensikan Domain SwaggerHub pada versi tertentu, dan versi Domain tersebut sudah tidak berlaku (`deprecated`) atau dimodifikasi secara tidak kompatibel, API yang mereferensikan mungkin mengalami kesalahan resolusi. Ini bukan konflik sinkronisasi secara harfiah, tetapi menyebabkan gangguan serupa dan memerlukan langkah-langkah resolusi yang serupa.
5. Konflik `Git pull` di repositori yang terhubung. Ketika repositori Git yang terhubung ke SwaggerHub memiliki cabang atau penggabungan yang menghasilkan konflik pada file spesifikasi, proses sinkronisasi SwaggerHub akan menampilkan konflik tersebut pada sinkronisasi berikutnya.
Mengatasi konflik pengeditan bersamaan
Jenis "konflik" ini adalah yang paling umum dan paling tidak terlihat. Tidak ada pesan kesalahan — perubahan salah satu pengguna hanya menghilang.
Resolusi:
- Jika Anda melihat perubahan hilang setelah anggota tim lain menyimpan, periksa riwayat perubahan SwaggerHub (jika tersedia di paket Anda) untuk melihat apa yang telah ditimpa.
- Minta anggota tim yang terakhir menyimpan untuk membandingkan status spesifikasi saat ini dengan salinan lokal mereka.
- Masukkan kembali perubahan yang hilang secara manual.
Pencegahan adalah satu-satunya perbaikan nyata. Lihat bagian pencegahan di bawah ini.
Mengatasi konflik sinkronisasi SwaggerHub-ke-Git
Ketika SwaggerHub dan repositori Git Anda telah berbeda, Anda biasanya akan melihat kesalahan sinkronisasi di panel integrasi Git SwaggerHub yang menunjukkan bahwa ia tidak dapat melakukan `auto-push` karena `remote` memiliki perubahan yang tidak ada dalam versi SwaggerHub.
Langkah-langkah resolusi:
Langkah 1: Tarik (`pull`) spesifikasi saat ini dari repositori Git Anda. Unduh file YAML atau JSON dari cabang yang menyebabkan konflik.
Langkah 2: Tarik (`pull`) spesifikasi saat ini dari SwaggerHub. Ekspor API sebagai YAML dari SwaggerHub.
Langkah 3: Lakukan `diff` pada kedua file. Gunakan alat `diff` apa pun (`diff`, tampilan `diff` VS Code, atau alat `diff` yang memahami OpenAPI). Identifikasi perubahan mana yang ada di Git yang tidak ada di SwaggerHub, dan sebaliknya.
Langkah 4: Gabungkan secara manual. Buat versi spesifikasi yang direkonsiliasi yang mencakup kedua set perubahan. Ini memerlukan penilaian manusia — alat penggabungan otomatis dapat menghasilkan YAML yang secara sintaksis valid tetapi secara semantik salah.
Langkah 5: Pilih satu sumber kebenaran. Putuskan apakah SwaggerHub atau Git adalah sumber yang otoritatif, lalu perbarui yang lainnya. Jika Git otoritatif, komit spesifikasi yang digabungkan ke repositori dan biarkan sinkronisasi menariknya ke SwaggerHub. Jika SwaggerHub otoritatif, dorong (`push`) spesifikasi yang digabungkan dari SwaggerHub ke Git.
Langkah 6: Verifikasi sinkronisasi. Setelah memperbarui, konfirmasikan bahwa panel integrasi Git SwaggerHub menunjukkan status sinkronisasi yang bersih tanpa konflik.
Alat yang berguna: `openapi-diff`. Beberapa alat `diff` OpenAPI membandingkan versi spesifikasi pada tingkat semantik (penambahan titik akhir, perubahan bidang, perubahan `breaking` vs. `non-breaking`) daripada baris per baris. Alat seperti `oasdiff` atau `openapi-diff` memberikan output yang lebih jelas daripada `diff` YAML mentah.
Mengatasi konflik ketidakcocokan versi Domain
Jika API Anda mereferensikan versi Domain yang telah berubah atau tidak berlaku lagi:
Langkah 1: Identifikasi versi Domain mana yang direferensikan oleh API Anda. Lihat URL `$ref` di spesifikasi Anda — URL tersebut menyertakan nomor versi.
Langkah 2: Tinjau `changelog` untuk versi Domain. Periksa apa yang berubah antara versi yang Anda sematkan saat ini dan versi terbaru.
Langkah 3: Evaluasi apakah perubahan tersebut `breaking`. Menambahkan bidang opsional baru tidak `breaking`. Menghapus bidang, mengubah tipe, atau mengganti nama properti adalah perubahan yang `breaking`.
Langkah 4: Perbarui jalur `$ref` API Anda untuk mereferensikan versi Domain baru jika Anda memutuskan untuk migrasi. Uji bahwa spesifikasi masih tervalidasi dengan benar setelah pembaruan.
Langkah 5: Perbarui tim. Jika perubahan Domain memengaruhi banyak API, koordinasikan migrasi agar semua tim memperbarui sesuai jadwal yang sama.
Mengatasi konflik percabangan versi API
Saat menggabungkan versi API yang bercabang kembali ke versi utama:
Langkah 1: Ekspor kedua versi, baik cabang (`fork`) maupun versi utama, sebagai file YAML.
Langkah 2: Lakukan `diff` pada kedua spesifikasi menggunakan alat `diff` OpenAPI.
Langkah 3: Di editor SwaggerHub, terapkan perubahan dari cabang (`fork`) secara manual ke versi utama (atau sebaliknya, tergantung pada mana yang menjadi status akhir yang diinginkan).
Langkah 4: Validasi spesifikasi yang digabungkan di editor SwaggerHub untuk memastikan tidak ada kesalahan validasi.
Langkah 5: Hapus atau arsipkan cabang (`fork`) jika tidak lagi diperlukan.
Pencegahan: mengurangi konflik sebelum terjadi
Tetapkan zona kepemilikan yang jelas. Alokasikan bagian-bagian berbeda dari spesifikasi API yang besar kepada anggota tim yang berbeda. Satu orang memiliki titik akhir autentikasi, yang lain memiliki titik akhir sumber daya. Zona pengeditan yang tumpang tindih adalah tempat konflik bersamaan terjadi.
Gunakan percabangan (`forking`) untuk perubahan yang tidak sepele. Untuk setiap perubahan yang akan memakan waktu lebih dari satu jam atau memerlukan tinjauan, buat cabang (`fork`) versi API sebelum mengedit. Ini mengisolasi pekerjaan Anda dari versi utama hingga Anda siap untuk menggabungkan.
Tetapkan protokol sinkronisasi Git. Jika Anda menggunakan integrasi Git, putuskan dan dokumentasikan arah mana yang otoritatif. "SwaggerHub adalah editor; Git adalah catatan" atau "Git adalah sumber kebenaran; SwaggerHub melakukan sinkronisasi darinya" — bukan keduanya secara bersamaan dengan pengeditan independen di setiap sisi.
Berkomunikasi sebelum mengedit area bersama. Gunakan Slack, sistem tiket, atau fitur komentar SwaggerHub sendiri untuk memberi sinyal saat Anda akan mengedit bagian yang mungkin juga perlu disentuh oleh orang lain. Komunikasi asinkron mencegah sebagian besar penimpaan pengeditan bersamaan.
Sematkan referensi Domain secara eksplisit. Selalu referensikan versi Domain tertentu di jalur `$ref` Anda, bukan referensi "terbaru" yang mengambang. Ini mencegah perubahan `breaking` otomatis mengalir ke API Anda tanpa tindakan yang disengaja.
Atur pengaturan `auto-push` dengan hati-hati. `Auto-push-on-save` SwaggerHub dapat nyaman tetapi menciptakan risiko konflik jika anggota tim juga mengkomit perubahan spesifikasi langsung di repositori Git. Nonaktifkan `auto-push` jika Anda memiliki pengembang yang membuat perubahan spesifikasi di kedua tempat.
Bagaimana Apidog menangani masalah yang sama
Model kolaborasi Apidog dibangun berdasarkan `branching` gaya Git, yang mencegah sebagian besar pola konflik ini secara desain.
Tidak ada penimpaan bersamaan. Di Apidog, anggota tim bekerja pada cabang terpisah. Seorang insinyur yang membuat titik akhir baru membuat cabang, melakukan pekerjaan, dan membuka permintaan tinjauan setelah selesai. Insinyur lain yang membuat perubahan berbeda melakukan hal yang sama pada cabang terpisah. Perubahan tidak bergabung ke cabang utama sampai ditinjau dan disetujui. Ini sepenuhnya menghilangkan masalah penimpaan "penyimpanan terakhir yang menang".
`Gate` tinjauan bawaan. Alur kerja tinjauan dan persetujuan berarti perubahan spesifikasi melalui langkah verifikasi eksplisit sebelum memengaruhi cabang utama atau dokumentasi yang digunakan oleh tim hilir.
Deteksi konflik pada penggabungan. Ketika dua cabang memodifikasi titik akhir atau skema yang sama, proses penggabungan Apidog secara eksplisit memunculkan konflik. Tim menyelesaikannya dengan pandangan yang jelas tentang kedua set perubahan.
Alur kerja `local-first`. Untuk tim yang khawatir tentang konflik sinkronisasi dengan repositori Git eksternal, alur kerja lokal Apidog mengurangi `blast radius` — perubahan divalidasi di platform sebelum dikomit ke Git.
FAQ
Apakah ada UI resolusi konflik bawaan di SwaggerHub? SwaggerHub tidak memiliki antarmuka resolusi konflik penggabungan grafis seperti beberapa alat GUI Git. Resolusi konflik bersifat manual — unduh kedua versi, `diff` di luar SwaggerHub, dan unggah versi yang sudah diselesaikan.
Alat `diff` OpenAPI terbaik apa yang harus digunakan selama resolusi konflik? `oasdiff` adalah alat baris perintah yang terawat dengan baik yang menghasilkan `diff` terstruktur dari spesifikasi OpenAPI, menandai perubahan `breaking` secara terpisah dari penambahan `non-breaking`. Ini adalah output yang lebih berguna daripada `diff` YAML mentah untuk pekerjaan spesifikasi API.
Bisakah saya mengunci API di SwaggerHub untuk mencegah orang lain mengeditnya? SwaggerHub tidak memiliki mekanisme penguncian file bawaan. Solusi terdekat adalah menggunakan sistem peran SwaggerHub untuk sementara membatasi izin edit saat Anda membuat perubahan, lalu memulihkannya.
Bagaimana saya tahu versi API yang bertentangan mana yang benar? Periksa log aktivitas SwaggerHub (jika paket Anda menyertakannya) untuk melihat siapa yang membuat perubahan apa dan kapan. Jika Anda menggunakan Git, riwayat komit adalah catatan yang dapat diandalkan. Jika keduanya tidak meyakinkan, konsultasikan dengan anggota tim yang terlibat untuk merekonstruksi maksud.
Apakah SwaggerHub memberi tahu saya ketika Domain yang saya bergantung padanya diperbarui? SwaggerHub dapat memberi tahu Anda tentang pembaruan Domain melalui sistem notifikasinya. Apakah Anda telah mengonfigurasi ini tergantung pada pengaturan notifikasi Anda. Periksa Pengaturan Organisasi > Notifikasi untuk mengonfigurasi peringatan untuk perubahan Domain.
Apakah migrasi ke Apidog mencegah semua konflik sinkronisasi? `Branching` mengurangi frekuensi konflik secara signifikan, tetapi tidak menghilangkannya sepenuhnya. Dua cabang yang keduanya memodifikasi titik akhir yang sama masih perlu direkonsiliasi saat digabungkan. Yang dilakukan `branching` adalah membuat konflik-konflik itu terlihat dan eksplisit daripada penimpaan yang diam-diam.
Konflik sinkronisasi di SwaggerHub sebagian besar adalah masalah alur kerja, bukan masalah produk. Kepemilikan yang jelas, disiplin cabang, dan protokol sinkronisasi Git yang terdefinisi mencegah sebagian besar masalah sebelum terjadi. Ketika konflik memang terjadi, proses yang metodis — ekspor kedua versi, `diff` dengan alat yang sesuai, gabungkan secara manual, validasi, dan verifikasi sinkronisasi — menyelesaikannya dengan andal. Model `branching` Apidog mengurangi frekuensi konflik dengan membuat pekerjaan paralel eksplisit, tetapi setiap alat pengeditan kolaboratif mendapat manfaat dari disiplin dasar yang sama.