Cara Mengontrol Versi OpenAPI Spec dengan Git

Spesifikasi OpenAPI Anda adalah sebuah kontrak. Ketika spesifikasi itu melenceng, klien akan terganggu, _mock_ menjadi usang, dan _test_ akan berjalan terhadap API yang sudah tidak ada. Jadi perlakukan spesifikasi tersebut seperti kode Anda yang lain: letakkan di Git, buat _branch_, tinjau, dan validasi setiap perubahannya.

Panduan ini akan membahas kontrol versi OpenAPI dengan Git dari awal. Di mana _file_ disimpan, cara membuat _branch_, apa yang sebenarnya dicari oleh peninjau dalam _diff_ spesifikasi, dan cara mendorong perubahan langsung dari Apidog. Pada akhirnya, Anda akan memiliki alur kerja yang dapat dipercaya oleh seluruh tim Anda.

Mengapa Mengontrol Versi Spesifikasi OpenAPI Anda

Spesifikasi yang disimpan di wiki atau _shared drive_ tidak memiliki riwayat. Anda tidak bisa melihat siapa yang mengubah _payload_ POST /orders Selasa lalu, atau mengapa. Git memperbaikinya.

Tempatkan openapi.yaml di bawah kontrol versi dan Anda mendapatkan empat hal secara gratis:

• Riwayat. Setiap perubahan adalah _commit_ dengan penulis, stempel waktu, dan pesan.
• Blame. git blame openapi.yaml memberi tahu Anda siapa yang menambahkan _field_ yang wajib tersebut dan kapan.
• _Rollback_. _Merge_ yang buruk yang merusak kontrak? _Revert_ _commit_ tersebut dan Anda kembali ke spesifikasi yang berfungsi.
• Peninjauan. Perubahan spesifikasi melalui _pull request_, jadi orang kedua melihat _diff_ sebelum dirilis.

Ini adalah fondasi dari alur kerja API Git-native: spesifikasi adalah kode sumber, dan kode sumber berada di Git.

Di Mana File Spesifikasi Berada di Repo

Jaga agar tetap sederhana dan dapat diprediksi. Sebagian besar tim menempatkan satu openapi.yaml di _root repo_ atau di folder api/:

my-service/
├── api/
│ └── openapi.yaml
├── src/
└── README.md

Ketika Anda mengelola beberapa versi mayor secara paralel, pisahkan berdasarkan versi dengan satu _file_ per mayor:

api/
├── api-v1.yaml
└── api-v2.yaml

Ini menjaga perubahan yang merusak tetap terisolasi. api-v1.yaml tetap beku untuk klien yang sudah ada sementara api-v2.yaml berkembang. Ini juga membuat _diff_ lebih kecil dan peninjauan lebih cepat, karena setiap _file_ berubah karena satu alasan. Memperlakukan spesifikasi dengan cara ini adalah ide inti di balik spesifikasi API sebagai kode.

Pilih satu konvensi dan dokumentasikan. Hasil terburuk adalah dua _file_ yang mengklaim sebagai spesifikasi “yang sebenarnya”.

Strategi Branching untuk Perubahan Spesifikasi

Anda tidak memerlukan model _branching_ khusus untuk spesifikasi. Gunakan kembali apa yang sudah dilakukan oleh kode Anda. Buat _branch_ dari main, lakukan perubahan, buka PR.

konvensi penamaan yang membuat _branch_ spesifikasi mudah dipindai:

Prefix api/ menandakan “PR ini menyentuh kontrak” sekilas. Peninjau dan CI dapat memfilternya. Untuk perubahan yang merusak, prefix eksplisit breaking- adalah tanda bahwa ini memerlukan perhatian ekstra dan kemungkinan peningkatan versi.

Jaga agar _branch_ berumur pendek. _Branch_ spesifikasi yang hidup selama dua minggu akan bertabrakan dengan perubahan orang lain. _Branch_ yang kecil dan fokus akan bergabung dengan bersih.

Meninjau Perubahan Spesifikasi dalam _Pull Request_

Di sinilah kontrol versi menunjukkan nilainya. PR spesifikasi adalah perubahan kontrak, dan perubahan kontrak layak mendapatkan peninjauan yang serius.

Tulis YAML dengan cara yang ramah _diff_ sehingga peninjau dapat membaca perubahannya, bukan melawan formatnya:

paths:
 /orders/{orderId}:
 get:
 summary: Get an order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Order found
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"

Inden yang konsisten dan satu properti per baris berarti penambahan satu _field_ muncul sebagai _diff_ satu baris. Itulah tujuannya.

Apa yang harus diperiksa oleh peninjau:

• Perubahan yang merusak. Apakah _field_ yang wajib ditambahkan ke permintaan? Apakah _field_ respons dihapus atau diganti namanya? Apakah _enum_ kehilangan nilai? Masing-masing dapat merusak klien yang sudah ada.
• Kompatibilitas mundur. _Field_ opsional baru dan _endpoint_ baru aman. Perubahan pada bentuk yang sudah ada tidak aman.
• Penamaan dan konsistensi. Apakah _endpoint_ baru cocok dengan _casing_ dan bentuk jamak dari API lainnya?
• Kelengkapan. Setiap operasi baru memerlukan summary, skema respons, dan respons kesalahan.
• Contoh. Contoh yang realistis membuat dokumentasi dan _mock_ berguna.

Untuk deteksi perubahan yang merusak, andalkan alat daripada mata telanjang. Langkah CI (dibahas di bawah) dapat membandingkan spesifikasi PR dengan main dan menggagalkan _build_ jika mendeteksi perubahan yang tidak kompatibel. Manusia melewatkan ini; alat _diff_ tidak.

_Commit_ & _Push_ dari Apidog

Mengedit YAML mentah secara manual memang berfungsi, tetapi editor visual dengan validasi langsung lebih cepat dan mendeteksi kesalahan lebih awal. Mode Spec-First Apidog memberi Anda sinkronisasi Git dua arah: edit spesifikasi di UI, _commit_, dan _push_ ke _repo_ Anda tanpa meninggalkan alat. Tarik kembali perubahan rekan tim dengan cara yang sama.

Alur kerjanya terlihat seperti ini:

1. Hubungkan _repo_ Git Anda dan arahkan Apidog ke _file_ spesifikasi.
2. Edit _endpoint_, skema, dan contoh di editor visual.
3. Apidog menulis YAML yang bersih dan ramah _diff_ kembali ke _file_.
4. _Commit_ pada _branch_ dan _push_, lalu buka PR Anda seperti biasa.

Karena Apidog _menserialisasi_ YAML secara konsisten, _diff_ Anda tetap kecil dan dapat ditinjau, tidak ada pengurutan ulang atau pemformatan ulang yang berisik. Anda dapat membaca _setup_ lengkapnya di dokumentasi Apidog Spec-First Mode. Jika Anda ingin _file_ tersebut mendarat di penyedia tertentu, lihat menyinkronkan spesifikasi OpenAPI Anda ke GitHub.

_Hook_ Validasi CI

Jangan pernah biarkan spesifikasi yang tidak valid mencapai main. Integrasikan validasi ke dalam pemeriksaan _pull request_ Anda sehingga kontrak yang rusak akan menggagalkan _build_ secara otomatis.

Langkah GitHub Actions minimal:

name: Validate OpenAPI
on: [pull_request]
jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Lint spec
 run: npx @redocly/cli lint api/openapi.yaml

Tambahkan lebih banyak pemeriksaan seiring pertumbuhan Anda:

• Lakukan _lint_ spesifikasi untuk masalah struktural dan gaya.
• Validasi bahwa ia diuraikan sebagai OpenAPI 3.x yang sah.
• Bandingkan dengan main untuk mendeteksi perubahan yang merusak dan menandainya pada PR.

Pemeriksaan ini berjalan dalam hitungan detik dan menangkap kesalahan yang terlewatkan oleh peninjau manusia.

Praktik Terbaik

Beberapa kebiasaan menjaga kontrol versi spesifikasi tetap sehat seiring waktu:

• Gunakan _semantic versioning_. Tingkatkan _field_ info.version. Perubahan yang merusak berarti mayor baru; penambahan yang kompatibel mundur meningkatkan minor.
• Buat _changelog_. _File_ CHANGELOG.md singkat di samping spesifikasi memberi tahu konsumen apa yang berubah di antara versi.
• Kirim _diff_ kecil. Satu perubahan logis per PR. PR spesifikasi besar menyembunyikan perubahan yang merusak dalam kebisingan.
• Tulis pesan _commit_ yang deskriptif. “Tambah refundReason ke permintaan pengembalian dana” lebih baik daripada “perbarui spesifikasi.”
• Jangan pernah mengedit spesifikasi yang digabungkan langsung di main. Selalu buat _branch_, bahkan untuk kesalahan ketik.

FAQ

Bagaimana cara mendeteksi perubahan yang merusak dalam spesifikasi OpenAPI?

Jalankan alat _spec-diff_ di CI yang membandingkan _pull request_ dengan versi di main. Alat seperti oasdiff mengklasifikasikan setiap perubahan sebagai merusak, tidak merusak, atau tidak terklasifikasi, dan dapat menggagalkan _build_ pada perubahan yang merusak. Ini menangkap _field_ yang dihapus, parameter wajib baru, dan jenis yang diubah yang mungkin terlewatkan oleh peninjauan manual.

Haruskah saya menyimpan satu _file_ OpenAPI atau membaginya menjadi banyak?

Mulai dengan satu openapi.yaml. Ini yang paling mudah untuk ditinjau dan dikontrol versinya. Ketika _file_ menjadi besar atau Anda mengelola beberapa versi mayor secara paralel, pisahkan berdasarkan versi mayor (api-v1.yaml, api-v2.yaml) atau gunakan $ref untuk memecah skema menjadi _file_ terpisah. Jangan memecah terlalu dini; satu _file_ yang mudah dibaca lebih baik daripada lima _file_ yang terfragmentasi.

Bisakah saya mengontrol versi spesifikasi saya tanpa menulis YAML secara manual?

Ya. Mode Spec-First Apidog memungkinkan Anda mengedit spesifikasi di editor visual dan menyinkronkan perubahan ke Git dalam dua arah. Ini menulis YAML yang konsisten, sehingga _diff_ Anda tetap bersih dan _pull request_ Anda tetap mudah dibaca, sementara Anda tetap mendapatkan riwayat dan peninjauan Git penuh.