Cara Sinkronisasi OpenAPI Spec ke GitHub: 2 Metode Ampuh

Jika dokumen OpenAPI Anda berada di repositori Git tetapi Anda mengeditnya di dalam klien API, Anda pasti sudah tahu kesulitannya: menyalin YAML keluar, menempelkannya kembali, berharap tidak ada orang lain yang menyentuh file tersebut, dan berharap proses impor tidak secara diam-diam menghapus sebuah bidang. Menjaga spesifikasi dan repositori tetap selaras secara manual adalah jenis pekerjaan yang akan rusak tepat saat Anda sedang terburu-buru.

Panduan ini menunjukkan cara menyinkronkan spesifikasi OpenAPI Anda ke GitHub dengan Mode Spec-First Apidog, sehingga spesifikasi di repositori Anda dan spesifikasi di editor Anda tetap sama alih-alih dua salinan yang terus-menerus Anda rekonsiliasi. Kami akan menghubungkan penyedia, membuka proyek langsung dari repositori, mengedit YAML, dan mendorong perubahan kembali ke GitHub dalam sekali jalan. Langkah-langkah yang sama juga berlaku untuk GitLab.

Mari kita mulai.

Apa arti sinkronisasi dua arah sebenarnya

Sinkronisasi dua arah berarti perubahan mengalir di kedua arah, secara otomatis, tanpa langkah ekspor di tengah-tengah.

• Apidog ke Git: Saat Anda mengedit dokumen OpenAPI di Apidog dan melakukan commit, perubahan akan didorong ke repositori Anda sebagai commit Git normal pada cabang yang Anda pilih.
• Git ke Apidog: Ketika rekan tim (atau Anda, dari IDE Anda) mendorong perubahan ke cabang tersebut, Apidog akan menariknya kembali sehingga editor Anda mencerminkan apa yang sebenarnya ada di repositori.

Repositori adalah satu-satunya sumber kebenaran. Apidog adalah editor kaya di atasnya. Itulah seluruh ide di balik alur kerja API native-Git: spesifikasi di-versi, ditinjau, dan dilacak riwayatnya seperti file lain dalam basis kode Anda, alih-alih berada di alat yang secara berkala mengekspor snapshot.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

• Apidog terinstal (aplikasi desktop atau web), masuk.
• Repositori GitHub atau GitLab yang sudah berisi dokumen OpenAPI, atau yang Anda miliki akses tulisnya. Azure DevOps juga didukung melalui Git Connection.
• Mode Spec-First (beta) diaktifkan. Ini adalah mode yang mengubah proyek Anda menjadi lapisan tipis di atas repositori Git daripada penyimpanan Apidog sendiri.

Anda akan membutuhkan izin tulis pada cabang yang akan Anda sinkronkan. Akses hanya-baca memungkinkan Anda menarik tetapi tidak mendorong.

Langkah 1: Hubungkan penyedia Git Anda

Pertama, otorisasi Apidog untuk berkomunikasi dengan penyedia Anda.

1. Buka Apidog dan buat proyek baru, pilih Mode Spec-First.
2. Ketika diminta untuk memilih sumber, pilih penyedia Anda, GitHub atau GitLab.
3. Klik Otorisasi. Browser Anda akan membuka layar OAuth penyedia.
4. Berikan akses Apidog ke repositori yang ingin Anda sinkronkan. Di GitHub, Anda dapat membatasi ini ke repo tertentu daripada seluruh akun Anda.

Setelah otorisasi selesai, Anda akan dikembalikan ke Apidog dengan penyedia yang sudah terhubung. Anda hanya perlu melakukan ini sekali per penyedia, proyek di masa mendatang akan menggunakan kembali koneksi tersebut.

Untuk referensi lengkap tentang alur ini, termasuk Azure DevOps melalui Git Connection, lihat dokumentasi Mode Spec-First.

Langkah 2: Buat proyek dari repositori dan cabang

Sekarang arahkan Apidog ke spesifikasi sebenarnya.

1. Dengan penyedia terhubung, pilih repositori yang berisi file OpenAPI Anda.
2. Pilih cabang untuk disinkronkan, biasanya main. Ini adalah cabang tempat commit Anda akan mendarat dan cabang yang diawasi Apidog untuk perubahan yang masuk.
3. Konfirmasikan jalur ke dokumen OpenAPI jika Apidog bertanya (misalnya openapi.yaml di root repositori, atau di bawah docs/).
4. Buat proyek.

Apidog mengkloning spesifikasi dari cabang tersebut dan membukanya. Sidebar kiri terisi dengan endpoint dan skema Anda, karena Apidog menguraikan dokumen menjadi garis besar yang dapat dinavigasi. Anda sekarang melihat spesifikasi repositori, secara langsung.

Langkah 3: Edit YAML OpenAPI Anda di editor kode

Mode Spec-First memberi Anda editor gaya IDE untuk YAML OpenAPI mentah, dengan penyorotan sintaks, validasi inline, dan pelengkapan otomatis. Anda menulis OpenAPI secara langsung; Apidog menjaga garis besar visual tetap selaras saat Anda mengetik.

Mari tambahkan endpoint kecil. Misalkan Anda ingin pemeriksaan kesehatan:

paths:
 /health:
 get:
 summary: Service health check
 operationId: getHealth
 responses:
 '200':
 description: Service is up
 content:
 application/json:
 schema:
 type: object
 properties:
 status:
 type: string
 example: ok

Saat Anda mengetik, dua hal terjadi. Sidebar kiri secara otomatis menguraikan garis besar, sehingga operasi /health baru Anda muncul di pohon secara instan. Dan validator menandai masalah secara inline, blok responses yang hilang, $ref yang salah, kesalahan indentasi, sebelum Anda melakukan commit. Jika YAML salah format, Anda akan melihatnya digarisbawahi daripada menemukannya dalam pipeline yang gagal nanti.

Ini juga tempat di mana kontrol versi menunjukkan nilainya. Jika Anda ingin melihat lebih dalam tentang bagaimana diff dan riwayat berfungsi pada spesifikasi, panduan tentang kontrol versi OpenAPI dengan Git akan menjelaskannya.

Langkah 4: Commit dan push

Ketika editan terlihat benar, kirimkan ke GitHub.

1. Buka panel commit (area Git/kontrol-sumber proyek).
2. Tinjau perubahan. Apidog menunjukkan apa yang dimodifikasi dibandingkan dengan versi yang disinkronkan.
3. Tulis pesan commit, perlakukan seperti commit lainnya: Add /health endpoint.
4. Klik Commit & Push.

Apidog melakukan commit ke cabang yang Anda pilih dan mendorong ke remote. Buka repositori Anda di GitHub dan Anda akan melihat commit dalam riwayat cabang, yang ditulis seperti yang diharapkan, hanya menyentuh file OpenAPI.

Berubah pikiran sebelum mendorong? Anda dapat membuang editan yang belum didorong untuk mengembalikan dokumen ke status sinkronisasi terakhir. Tidak ada yang meninggalkan Apidog sampai Anda melakukan commit, jadi eksperimen lokal tetap lokal.

Langkah 5: Verifikasi status sinkronisasi

Apidog menampilkan indikator sinkronisasi agar Anda selalu tahu di mana posisi Anda.

Setelah dorongan yang berhasil, indikator akan berbunyi "Disinkronkan barusan." Itu adalah konfirmasi Anda bahwa editor dan cabang remote memegang dokumen yang sama. Seiring berjalannya waktu, ia akan diperbarui ("Disinkronkan 5 menit yang lalu") dan, ketika orang lain mendorong, Apidog akan menarik perubahan dan mengatur ulang indikator setelah rekonsiliasi.

Jika indikator menunjukkan status tertunda atau usang, itu berarti salinan lokal dan remote telah menyimpang, tanda bagi Anda untuk menarik atau menyelesaikan sebelum melanjutkan.

Pemecahan masalah

Beberapa hal cenderung membuat orang kesulitan untuk pertama kalinya.

• Otorisasi kedaluwarsa atau dicabut. Jika dorongan mulai gagal dengan kesalahan izin, jalankan ulang otorisasi dari Langkah 1. Token dapat dicabut di sisi penyedia atau hanya habis waktu.
• Cabang salah. Mendorong ke main yang dilindungi yang memerlukan permintaan tarik akan ditolak. Sinkronkan terhadap cabang yang ada atau sesuaikan aturan perlindungan cabang. Periksa kembali cabang yang dipilih di Langkah 2 cocok dengan tempat Anda mengharapkan commit mendarat.
• Konflik penggabungan. Jika rekan tim mendorong ke cabang yang sama saat Anda mengedit, remote bergerak mendahului salinan lokal Anda. Tarik yang terbaru, selesaikan YAML yang tumpang tindih, dan commit lagi. Karena spesifikasi adalah teks biasa, konflik diselesaikan dengan cara yang sama seperti konflik kode lainnya.
• Kesalahan validasi menghalangi alur Anda. Apidog tidak akan menghentikan Anda untuk melakukan commit YAML yang tidak valid, tetapi Anda harus memperbaiki apa yang ditandai oleh validator inline terlebih dahulu. Spesifikasi yang bersih menjaga dokumentasi, mock, dan tes yang dihasilkan tetap jujur.

FAQ

Apakah sinkronisasi ke GitHub juga berfungsi dengan GitLab dan Azure DevOps?

Ya. Mode Spec-First mendukung GitHub dan GitLab secara langsung, dan Azure DevOps melalui Git Connection. Alur menghubungkan-mengedit-melakukan commit-mendorong sama di ketiganya; hanya layar otorisasi yang berbeda per penyedia.

Apa yang terjadi jika rekan tim mengedit spesifikasi di repo saat saya bekerja di Apidog?

Apidog menarik perubahan mereka kembali ke editor Anda sebagai bagian dari sinkronisasi dua arah. Jika editan Anda dan editan mereka menyentuh bagian file yang berbeda, mereka akan digabungkan dengan bersih. Jika tumpang tindih, Anda akan menyelesaikan konflik Git standar, sama seperti yang Anda lakukan pada file teks apa pun.

Bisakah saya membatalkan perubahan sebelum mencapai GitHub?

Ya. Sampai Anda mengklik Commit & Push, editan Anda bersifat lokal. Gunakan "buang editan yang belum didorong" untuk mengembalikan dokumen ke status sinkronisasi terakhir, dan tidak ada yang mencapai remote.