Mode Spec-first (Beta)

Mode Spec-first ditujukan untuk tim yang ingin menjadikan file spesifikasi API sebagai sumber kebenaran. Dalam mode ini, Anda merancang dan memelihara file OpenAPI atau Swagger secara langsung di Apidog, meninjau pratinjau dokumentasi API yang dihasilkan saat Anda mengedit, dan menjaga file tetap tersinkronisasi dengan Git.

Gunakan Mode Spec-first ketika tim Anda sudah bekerja dengan file spesifikasi YAML atau JSON, meninjau perubahan API melalui Git, atau ingin agar desain API selaras secara alami dengan alur kerja repositori kode.

Cara Kerja Mode Spec-first

Dalam proyek Apidog reguler, API biasanya dibuat dan diedit melalui formulir visual. Dalam proyek Spec-first, ruang kerja utama berbasis file.

Anda bekerja dengan file seperti:

openapi.yaml

openapi.json

File Swagger 2.0

File Markdown dan file pendukung proyek lainnya

Apidog mengurai file spesifikasi dan mengubahnya menjadi struktur API yang dapat dinavigasi. Anda dapat mengedit file mentah, menggunakan formulir visual yang didukung, memvalidasi spesifikasi, meninjau pratinjau dokumentasi yang dihasilkan, dan mendorong perubahan kembali ke Git.

Membuat Proyek Spec-first

Klik + New Project.

Di pemilih jenis proyek, pilih Spec-first Mode.

Hubungkan penyedia Git, seperti GitHub, GitLab, Azure DevOps, atau Bitbucket.

Pilih organisasi atau workspace, lalu pilih repositori yang sudah ada atau buat repositori baru jika opsi tersebut tersedia.

Pilih branch utama yang harus disinkronkan oleh Apidog.

Pilih apakah akan memasang webhook.

Memasang webhook memungkinkan push di repositori Git memicu sinkronisasi otomatis. Ini biasanya memerlukan izin admin pada repositori. Jika Anda tidak memiliki izin admin, Anda dapat melewati pemasangan webhook dan melakukan sinkronisasi secara manual.

Masukkan nama proyek, konfigurasikan izin anggota, dan klik Create.

Setelah dibuat, Apidog melakukan sinkronisasi pertama. Jika branch default repositori bukan main, Apidog menggunakan nama branch repositori untuk branch utama proyek.

Proyek Spec-first tidak menyertakan data proyek contoh. Konten API berasal dari file spesifikasi Anda.

Ruang Kerja Specs

Proyek Spec-first menyertakan ruang kerja Specs di sidebar kiri. Ini adalah tempat utama untuk mengelola file spesifikasi dan sinkronisasi Git.

Ruang kerja ini berisi tiga area utama:

File explorer: Menelusuri dan mengelola file serta folder dari repositori yang disinkronkan.

Pohon struktur API: Menavigasi konten OpenAPI yang telah diurai, seperti ikhtisar, endpoint, skema, dan definisi.

Editor: Mengedit file dalam tampilan kode atau, untuk node OpenAPI yang didukung, dalam tampilan formulir.

Saat Anda memilih endpoint, skema, atau node lain yang didukung dalam pohon struktur, Apidog membuka bagian terkait dari file sumber. Ini memungkinkan Anda berpindah antara tampilan tingkat file dan tampilan tingkat API tanpa meninggalkan ruang kerja Specs.

Mengedit File Spesifikasi

Editor mendukung berbagai jenis file dan mode pengeditan.

Tampilan Kode

Gunakan tampilan Code untuk mengedit YAML, JSON, Markdown, dan file teks lainnya secara langsung. Ini adalah cara default untuk bekerja dalam Mode Spec-first.

Tampilan Formulir

Untuk node OpenAPI yang didukung, Apidog juga menyediakan tampilan Form. Ini memungkinkan Anda mengedit bidang API umum melalui kontrol terstruktur sambil tetap menjadikan file spesifikasi yang mendasarinya sebagai sumber kebenaran.

Tampilan formulir tersedia untuk node yang didukung seperti:

Ikhtisar API

Endpoint

Skema

Definisi

Jika file atau node yang dipilih tidak dapat diedit dalam tampilan formulir, Apidog tetap mempertahankan Anda dalam tampilan kode.

Memvalidasi dan Meninjau Pratinjau Saat Mengedit

Mode Spec-first menyertakan alat validasi dan pratinjau di header editor.

Validasi

Panel Validation menampilkan masalah yang terdeteksi dalam spesifikasi saat ini, termasuk peringatan dan kesalahan. Badge validasi menampilkan jumlah total masalah yang terdeteksi.

Gunakan panel ini untuk menemukan masalah sintaks, bidang wajib yang hilang, dan pelanggaran aturan sebelum melakukan commit perubahan.

Pratinjau

Panel Preview menampilkan bagaimana node spesifikasi yang dipilih akan muncul dalam dokumentasi API yang dihasilkan.

Pratinjau tersedia untuk:

Ikhtisar API

Endpoint

Skema

Definisi

Untuk endpoint, Preview mencakup:

Docs: Dokumentasi endpoint yang dihasilkan.

Try it out: Panel permintaan untuk mengirim permintaan berdasarkan definisi endpoint yang dipilih.

Untuk skema, definisi, dan node ikhtisar, Preview menampilkan tampilan dokumentasi yang dihasilkan.

Validation dan Preview menggunakan panel samping yang sama. Membuka salah satunya akan menutup yang lain.

Menyinkronkan Perubahan dari Git

Ketika anggota tim lain melakukan push perubahan ke repositori yang terhubung, Anda dapat menarik file terbaru ke Apidog.

Buka ruang kerja Specs.

Klik nama branch saat ini di sidebar Specs.

Klik Git Pull.

Jika sinkronisasi webhook dipasang, Apidog juga dapat menerima event push dari penyedia Git dan memicu sinkronisasi secara otomatis.

Commit dan Push Perubahan ke Git

Setelah mengedit file di Apidog, dorong perubahan Anda kembali ke repositori yang terhubung.

Edit satu atau beberapa file di ruang kerja Specs.

Klik Changes untuk meninjau file yang dimodifikasi, ditambahkan, diganti namanya, dan dihapus.

Klik Commit & Push.

Dalam modal Push to Git repo, pilih file yang ingin Anda sertakan.

Masukkan pesan commit.

Klik Push.

Jika Anda tidak ingin menyimpan edit lokal Anda, gunakan Discard all changes sebelum melakukan push.

Mengelola Branch

Mode Spec-first mendukung kolaborasi berbasis branch. Apidog memetakan branch Git yang disinkronkan ke branch proyek sehingga Anda dapat beralih antarversi spesifikasi.

Beralih Branch

Klik nama branch di sidebar Specs dan pilih branch lain dari dropdown.

Melacak Branch Git yang Sudah Ada

Jika sebuah branch ada di Git tetapi belum diimpor ke Apidog, klik Import New Branch, pilih branch tersebut, lalu impor. Apidog kemudian mulai melacak dan menyinkronkan branch tersebut.

Membuat Branch

Buka Project Settings > Git & Branches dan klik New Branch untuk membuat branch dari branch proyek yang sudah ada.

Menyinkronkan Ulang Branch

Jika sinkronisasi branch gagal atau file terlihat sudah tidak terbaru, gunakan Re-sync di Project Settings > Git & Branches. Ini mereset status sinkronisasi untuk branch tersebut dan mengimpor file lagi.

Melihat Log Sinkronisasi

Jika sinkronisasi gagal, buka tindakan branch dan pilih View Logs untuk memeriksa detail sinkronisasi.

Berhenti Melacak atau Menghapus Branch

Menghapus branch yang dilacak akan menghapusnya dari konfigurasi sinkronisasi Apidog. Untuk branch non-utama, catatan branch proyek juga dapat dihapus.

Sinkronisasi Webhook dan Izin

Sinkronisasi webhook bersifat opsional tetapi direkomendasikan untuk tim yang ingin Apidog tetap terbaru dengan push repositori.

Ketika sinkronisasi webhook diaktifkan:

Apidog mendaftarkan webhook pada penyedia Git yang terhubung.

Hanya event push yang didukung yang diproses.

Apidog memverifikasi tanda tangan atau token webhook sebelum menyinkronkan.

Persyaratan izin:

Memasang webhook biasanya memerlukan izin admin repositori.

Melakukan push perubahan memerlukan izin tulis.

Jika pemasangan webhook dilewati, sinkronisasi manual tetap tersedia.

Jika Anda melewati pemasangan webhook saat pembuatan proyek, Anda dapat memasangnya nanti dari Project Settings > Git & Branches.

Proyek Spec-first Berbasis Penyimpanan

Beberapa proyek Spec-first mungkin menggunakan penyimpanan internal Apidog alih-alih repositori Git eksternal.

Proyek ini tetap menggunakan ruang kerja Specs, pengeditan berbasis file, validasi, pratinjau, dan manajemen branch.

Label UI sedikit berbeda:

Git Pull muncul sebagai Sync.

Commit & Push muncul sebagai Save.

Informasi penyedia Git dan pengaturan webhook eksternal disembunyikan.

Catatan dan Batasan

Mode Spec-first saat ini masih dalam beta.

Ruang kerja Specs hanya muncul dalam proyek Spec-first.

Proyek Spec-first tidak membuat data API contoh.

File spesifikasi adalah sumber kebenaran. Perubahan harus dilakukan melalui ruang kerja Specs atau disinkronkan melalui Git.

Pemasangan webhook dapat gagal jika Anda tidak memiliki izin repositori yang cukup. Anda tetap dapat menggunakan sinkronisasi manual jika memiliki akses tulis.

Mode Spec-first (Beta)

Cara Kerja Mode Spec-first#

Membuat Proyek Spec-first#

Ruang Kerja Specs#

Mengedit File Spesifikasi#

Tampilan Kode#

Tampilan Formulir#

Memvalidasi dan Meninjau Pratinjau Saat Mengedit#

Validasi#

Pratinjau#

Menyinkronkan Perubahan dari Git#

Commit dan Push Perubahan ke Git#

Mengelola Branch#

Beralih Branch#

Melacak Branch Git yang Sudah Ada#

Membuat Branch#

Menyinkronkan Ulang Branch#

Melihat Log Sinkronisasi#

Berhenti Melacak atau Menghapus Branch#

Sinkronisasi Webhook dan Izin#

Proyek Spec-first Berbasis Penyimpanan#

Catatan dan Batasan#