Apa Itu Apidog Spec-First Mode

Mode Spec-First Apidog adalah ruang kerja beta yang dibangun untuk tim yang memperlakukan spesifikasi OpenAPI mereka sebagai kode sumber. Anda menulis spesifikasi secara langsung sebagai YAML atau JSON dalam editor bergaya IDE, lalu menyinkronkannya dua arah dengan repositori Git yang terhubung. Tidak ada editor berbasis formulir yang menghalangi Anda dan berkas. Spesifikasi adalah proyeknya. Jika Anda pernah ingin mengedit openapi.yaml di editor kode sungguhan dan mendorongnya ke GitHub tanpa meninggalkan alat API Anda, inilah mode yang tepat untuk Anda.

Panduan ini adalah referensi lengkap untuk mode ini sendiri. Panduan ini mencakup setiap kapabilitas, panduan pengaturan lengkap, untuk siapa mode ini, batasan yang diharapkan dari versi beta, dan FAQ praktis. Untuk ide yang lebih luas di balik pendekatan ini, lihat alur kerja API git-native kami.

Apa itu Mode Spec-First Apidog?

Mode Spec-First adalah mode pengeditan beta di Apidog di mana desain API Anda berbentuk dokumen OpenAPI mentah. Anda membuka berkas, mengedit YAML atau JSON, memvalidasinya, melakukan commit, dan mendorongnya ke Git. Apidog menjaga spesifikasi dan repo tetap sinkron di kedua arah. Tarik perubahan rekan tim dan editor Anda akan diperbarui. Dorong editan Anda dan repo akan diperbarui.

Ini dibangun khusus untuk satu jenis tim: orang-orang yang sudah menjalankan alur kerja Git native. Insinyur backend, tim platform, dan perusahaan yang mengutamakan API yang memverifikasi kontrak mereka dalam permintaan pull akan merasa nyaman. Berkas spesifikasi menjadi satu-satunya sumber kebenaran, dan Git menangani riwayat, tinjauan, dan percabangan sebagaimana ia melakukannya untuk sisa basis kode Anda.

Ini berbeda dari cara kerja sebagian besar alat API. Sebagian besar alat menyembunyikan spesifikasi di balik formulir grafis. Mode Spec-First menunjukkan berkas tersebut kepada Anda.

Mode Spec-First vs Mode Design-First secara sekilas

Apidog memiliki dua mode. Mode Design-First adalah editor visual berbasis formulir yang menjadi awal bagi sebagian besar tim. Mode Spec-First adalah pendekatan editor kode yang dibahas panduan ini. Berikut adalah versi singkatnya. Untuk perincian lengkap tentang kelebihan dan kekurangannya, baca perbandingan spec-first vs design-first kami.

Tidak ada mode yang "lebih baik." Keduanya melayani tim yang berbeda. Anda dapat beralih di antara keduanya, yang akan kami bahas di bawah ini.

Fitur-Fitur Utama

Mode Spec-First lebih dari sekadar kotak teks. Ini menggabungkan editor, navigator, integrasi Git, dan kontrol tim. Berikut adalah setiap kapabilitas secara detail.

Editor OpenAPI bergaya IDE

Pusat ruang kerja adalah editor kode lengkap untuk dokumen OpenAPI Anda. Anda mengedit YAML atau JSON mentah secara langsung. Ini berperilaku seperti editor yang sudah Anda gunakan setiap hari.

Anda mendapatkan penyorotan sintaksis yang mewarnai kunci, nilai, dan struktur sehingga berkas tetap dapat dibaca dalam skala besar. Anda mendapatkan validasi skema yang menandai kesalahan terhadap spesifikasi OpenAPI saat Anda mengetik, sehingga objek respons yang salah format atau bidang wajib yang hilang akan segera muncul. Anda mendapatkan penyelesaian otomatis yang disesuaikan untuk OpenAPI dan Swagger, yang menyarankan kata kunci, nama bidang, dan struktur yang valid saat Anda menulis.

Penyelesaian otomatis itu sangat penting saat Anda sedang mendalami skema dan tidak dapat mengingat apakah itu additionalProperties atau additionalItems. Editor mengetahui spesifikasi, jadi ia membantu Anda tetap benar.

sebagian kecil dari apa yang akan Anda edit:

paths:
 /users/{userId}:
 get:
 summary: Get a user by ID
 operationId: getUserById
 parameters:
 - name: userId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: A single user
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/User'

Kerangka yang dapat dinavigasi yang diurai secara otomatis

Berkas spesifikasi mentah akan cepat menjadi panjang. Sebuah API sungguhan dapat terdiri dari ribuan baris. Mode Spec-First mengatasinya dengan bilah sisi kiri yang secara otomatis mengurai berkas menjadi kerangka visual.

Saat Anda mengetik, Apidog membaca dokumen dan membangun struktur yang dapat dinavigasi: jalur, operasi, skema, dan komponen. Klik node mana pun di kerangka dan editor akan melompat ke posisi itu di berkas. Anda menavigasi berdasarkan makna, bukan dengan menggulir. Kerangka diperbarui secara langsung saat spesifikasi berubah, sehingga selalu mencerminkan apa yang sebenarnya ada di berkas.

Ini membuat openapi.yaml yang besar tetap dapat dikelola. Anda berpikir dalam istilah “operasi POST /orders,” bukan “baris 1.847.”

Sinkronisasi Git dua arah

Ini adalah inti dari mode ini. Mode Spec-First terhubung ke repositori Git Anda dan menyinkronkan spesifikasi di kedua arah.

GitHub dan GitLab didukung secara langsung. Azure DevOps berfungsi melalui Koneksi Git generik, yang memungkinkan Anda mengarahkan Apidog ke repo menggunakan kredensial Git standar. Setelah terhubung, menarik perubahan repo ke editor Anda, dan mendorong mengirimkan editan Anda kembali ke repo. Spesifikasi tetap konsisten di seluruh tim karena Git adalah tulang punggung bersama.

Jika Anda menginginkan panduan langkah demi langkah yang terfokus pada satu penyedia, panduan sinkronisasi spesifikasi OpenAPI ke GitHub kami menjelaskan alur tersebut secara rinci.

Commit, push, dan indikator status sinkronisasi

Anda tidak hanya menyimpan dan berharap. Mode Spec-First mengikuti model Git yang sudah Anda kenal. Saat Anda menyelesaikan pengeditan, Anda menulis pesan commit dan melakukan commit perubahan. Kemudian Anda mendorongnya ke repo yang terhubung.

Indikator status sinkronisasi membuat Anda terus terinformasi. Ini menunjukkan status seperti "Sinkronisasi baru saja" saat spesifikasi lokal Anda cocok dengan repo, dan berubah ketika Anda memiliki pekerjaan yang belum didorong. Anda selalu tahu apakah versi yang ada di hadapan Anda adalah versi yang dilihat rekan tim Anda. Tidak ada tebak-tebakan, tidak ada spesifikasi usang.

Pelacakan perubahan berkas

Sebelum Anda melakukan commit, Mode Spec-First menunjukkan kepada Anda persis apa yang berubah. Ini melacak modifikasi pada tingkat berkas dan menandai setiap entri sebagai dimodifikasi, ditambahkan, atau dihapus. Anda meninjau kumpulan perubahan seperti Anda meninjau output status Git.

Ini penting karena memberi Anda titik pemeriksaan. Anda dapat mengonfirmasi bahwa Anda melakukan commit editan yang benar dan tidak ada yang berlebihan. Dan jika Anda memutuskan bahwa sebuah eksperimen tidak berhasil, Anda dapat membuang editan yang belum didorong sebelum mencapai repo. Itu menjaga riwayat bersama Anda tetap bersih. Eksplorasi lokal tetap lokal sampai Anda memilih untuk mendorongnya.

Proyek yang dicakup oleh cabang dan repo dengan izin tim

Proyek Spec-First tidak mengambang dalam abstraksi. Anda membuatnya dari repositori tertentu dan cabang tertentu, biasanya main. Cakupan itu berarti proyek selalu mengarah ke tempat nyata di Git. Spesifikasi Anda, riwayat Anda, dan cabang Anda selaras.

Izin tim dikonfigurasi selama pengaturan. Anda memutuskan siapa yang dapat mengakses proyek dan apa yang dapat mereka lakukan, sehingga orang-orang yang mengerjakan kontrak adalah orang-orang yang Anda inginkan. Karena proyek terikat pada repo dan cabang, model akses Anda dapat mencerminkan model akses yang sudah Anda terapkan di Git.

Cara mengatur Mode Spec-First

Pengaturan adalah alur yang singkat dan linear. Ikuti langkah-langkah ini. Panduan resmi tersedia di docs.apidog.com/spec-first-mode-beta-2058268m0 jika Anda menginginkan tangkapan layar di sampingnya.

1. Ganti mode. Buka modul API di Apidog. Temukan pengalih mode di kiri bawah modul dan beralih dari Mode Design-First ke Mode Spec-First.
2. Hubungkan penyedia Git Anda. Otorisasi GitHub atau GitLab secara langsung. Untuk Azure DevOps, siapkan Koneksi Git generik dengan kredensial Git Anda.
3. Buat proyek dari repo Anda. Pilih repositori yang berisi spesifikasi Anda dan pilih cabang, biasanya main. Apidog menetapkan cakupan proyek baru ke repo dan cabang tersebut.
4. Konfigurasi izin tim. Selama pengaturan, tentukan siapa yang dapat mengakses proyek dan apa yang dapat mereka ubah.
5. Edit spesifikasi. Buka openapi.yaml atau openapi.json Anda di editor bergaya IDE. Gunakan kerangka di sebelah kiri untuk menavigasi. Manfaatkan validasi dan penyelesaian otomatis saat Anda menulis.
6. Commit perubahan Anda. Tulis pesan commit yang jelas. Tinjau perubahan yang dilacak terlebih dahulu. Buang apa pun yang tidak ingin Anda simpan.
7. Dorong ke repo. Dorong commit Anda ke cabang yang terhubung.
8. Verifikasi sinkronisasi. Periksa indikator status sinkronisasi. Ketika terbaca “Sinkronisasi baru saja,” spesifikasi dan repo Anda cocok.

Itulah seluruh alurnya: ganti, hubungkan, buat, edit, commit, push, verifikasi.

Alur kerja sehari-hari yang umum

Beginilah rasanya mode ini dalam praktik setelah diatur.

Anda memulai hari Anda dengan menarik pembaruan terbaru dari cabang yang terhubung, sehingga editor Anda mencerminkan apa yang digabungkan oleh rekan tim Anda semalam. Anda membuka kerangka, mengklik operasi yang sedang Anda kerjakan, dan mulai mengedit YAML. Endpoint baru membutuhkan badan permintaan, jadi Anda mendefinisikan skema. Penyelesaian otomatis membantu Anda mendapatkan nama bidang yang benar, dan validasi menangkap kesalahan ketik dalam $ref sebelum menjadi masalah.

Ketika endpoint terlihat bagus, Anda memeriksa pelacakan perubahan berkas. Ini menunjukkan modifikasi Anda. Anda menulis pesan commit seperti Add POST /invoices endpoint, melakukan commit, dan mendorongnya. Indikator status berubah menjadi “Sinkronisasi baru saja.” Seorang rekan tim meninjau perubahan dalam permintaan pull biasa, karena spesifikasi berada di Git seperti halnya yang lain.

Berikut adalah jenis penambahan yang akan Anda lakukan dalam alur tersebut:

components:
 schemas:
 Invoice:
 type: object
 required: [id, amount, currency]
 properties:
 id:
 type: string
 format: uuid
 amount:
 type: integer
 description: Amount in the smallest currency unit
 currency:
 type: string
 example: USD
 status:
 type: string
 enum: [draft, sent, paid]

Seluruh siklus tetap berada di dalam alat yang Anda percaya. Spesifikasi adalah kode, dan Anda memperlakukannya seperti kode.

Siapa yang sebaiknya menggunakan Mode Spec-First

Mode Spec-First lebih cocok untuk beberapa tim daripada yang lain. Jujurlah tentang tim yang mana Anda.

Gunakan Mode Spec-First jika tim Anda sudah menggunakan Git. Jika Anda meninjau kontrak API dalam permintaan pull, jika Anda ingin spesifikasi diverifikasi di samping kode layanan Anda, atau jika insinyur Anda lebih suka mengedit YAML secara langsung, mode ini menghilangkan gesekan. Ini sangat cocok untuk tim backend dan platform yang memperlakukan dokumen OpenAPI sebagai artefak kelas satu.

Pilih Mode Design-First sebagai gantinya jika Anda menginginkan pengalaman visual yang terpandu. Tim dengan non-insinyur yang berkontribusi pada desain, atau siapa pun yang lebih suka mengklik formulir daripada menulis YAML, akan bergerak lebih cepat di sana. Tim campuran di mana produk dan desain mempertimbangkan endpoint seringkali lebih suka editor visual. Tidak ada jawaban yang salah. Pilih mode yang sesuai dengan cara kerja tim Anda sebenarnya. Tulisan perbandingan kami membahas lebih dalam keputusan ini.

Batasan dan catatan beta

Mode Spec-First adalah versi beta. Kata itu memiliki arti sesungguhnya, jadi sesuaikan ekspektasi Anda.

Sebagai versi beta, mode ini masih dalam tahap pengembangan. Kapabilitas dan perilakunya dapat berubah seiring Apidog menyempurnakan mode berdasarkan umpan balik. Integrasi penyedia langsung mencakup GitHub dan GitLab saat ini, sementara Azure DevOps mengandalkan Koneksi Git generik daripada integrasi khusus. Jika tim Anda bergantung pada penyedia Git atau alur kerja tertentu, pastikan mode ini sesuai dengan kebutuhan Anda sebelum Anda mendedikasikan proyek penting ke mode ini.

Karena spesifikasi disinkronkan dengan repo langsung, disiplin Git yang normal berlaku. Lakukan commit dengan sengaja, dorong dengan niat, dan gunakan opsi buang saat sebuah editan seharusnya tidak dipublikasikan. Pelacakan perubahan berkas dan indikator sinkronisasi ada untuk menjaga Anda tetap aman, tetapi tanggung jawab untuk riwayat yang bersih tetap ada pada Anda. Perlakukan versi beta ini seperti Anda memperlakukan alat baru apa pun yang menyentuh cabang utama Anda: coba terlebih dahulu pada repo yang tidak kritis, lalu perluas setelah Anda percaya pada alurnya.

Keuntungan dari versi beta adalah pengaruh. Umpan balik awal membentuk arah pengembangan mode ini, jadi jika ada sesuatu yang hilang untuk alur kerja Anda, itu layak dilaporkan.

FAQ

Apakah Mode Spec-First gratis?

Mode Spec-First adalah fitur beta di dalam Apidog. Akses mengikuti paket Apidog Anda, jadi periksa ketersediaan mode ini berdasarkan paket Anda saat ini dan status beta. Karena masih dalam versi beta, cara termudah adalah mengaktifkannya di modul API dan melihat apakah tersedia untuk akun Anda.

Penyedia Git mana saja yang didukung?

GitHub dan GitLab didukung melalui integrasi langsung. Azure DevOps berfungsi melalui Koneksi Git generik, yang menggunakan kredensial Git standar untuk mengarahkan Apidog ke repositori Anda. Host Git lainnya mungkin juga berfungsi melalui koneksi generik itu, karena mengandalkan Git standar daripada API khusus penyedia.

Bisakah saya beralih kembali ke Mode Design-First?

Ya. Pengalih mode berada di kiri bawah modul API, dan Anda beralih antara Mode Spec-First dan Mode Design-First di sana. Anda tidak terkunci. Pilih mode yang sesuai dengan proyek yang ada di hadapan Anda.

Format berkas apa yang bisa saya edit?

Anda mengedit dokumen OpenAPI Anda sebagai YAML atau JSON mentah di editor bergaya IDE. Editor menyediakan penyorotan sintaksis, validasi skema, dan penyelesaian otomatis untuk OpenAPI dan Swagger, sehingga Anda tetap benar saat menulis dalam format mana pun.

Apa yang terjadi pada editan saya yang belum didorong?

Editan yang belum didorong tetap lokal sampai Anda mendorongnya. Mode Spec-First melacak setiap perubahan sebagai dimodifikasi, ditambahkan, atau dihapus, dan indikator sinkronisasi menunjukkan ketika Anda memiliki pekerjaan yang belum mencapai repo. Jika Anda memutuskan untuk tidak melakukan perubahan, buanglah sebelum mendorong dan itu tidak akan pernah masuk ke riwayat bersama Anda.

Kesimpulan

Mode Spec-First Apidog menyatukan editor OpenAPI dan Git di satu tempat. Anda mengedit spesifikasi sebagai YAML atau JSON, menavigasinya melalui kerangka yang diurai secara otomatis, memvalidasi saat Anda mengetik, dan menyinkronkan dua arah dengan GitHub, GitLab, atau Azure DevOps. Pesan commit, push, pelacakan perubahan, dan indikator sinkronisasi yang jelas memberi Anda alur kerja Git yang sudah Anda kenal, diterapkan pada kontrak API Anda.

Ini adalah versi beta, dan ditujukan untuk tim yang mengutamakan Git yang ingin spesifikasi menjadi kode sumber. Jika itu Anda, mode ini patut dicoba dengan serius. Aktifkan di modul API, hubungkan repositori, dan coba siklus edit-commit-push kecil untuk merasakan alurnya. Ketika Anda siap, coba Mode Spec-First di dokumen dan hubungkan ke repositori yang Anda percaya.