Panduan Migrasi Stoplight ke Apidog: Mengelola Spesifikasi OpenAPI dalam Mode Spec-First

Migrasi dari Stoplight ke Apidog bukan sekadar mengimpor satu file OpenAPI. Agar alur kerja tetap utuh, Anda perlu memigrasikan konteks proyek berbasis file: spesifikasi, dokumentasi Markdown, JSON Schema, gambar lokal, konfigurasi jalur, dan input navigasi.

Coba Apidog hari ini

Proyek Stoplight biasanya mencakup lebih dari endpoint API:

• File OpenAPI atau Swagger di Git
• Dokumentasi Markdown
• Model JSON Schema
• Gambar lokal yang direferensikan dokumentasi
• Konfigurasi .stoplight.json
• Navigasi dokumentasi dari toc.json
• Identitas seperti x-stoplight-id atau x-stoplight.id
• Koleksi Postman, file Bruno, pengujian CI, atau mock di alat lain

Jika hanya mengimpor OpenAPI, endpoint mungkin berhasil dipindahkan, tetapi dokumentasi, navigasi, model, pengujian, dan proses kolaborasi dapat terputus.

Mode Spesifikasi-Pertama Apidog membantu menjaga file OpenAPI sebagai sumber kebenaran sambil menghubungkannya ke dokumentasi, mock, pengujian, laporan, izin, dan kolaborasi tim.

Untuk pengaturan operasional, lihat panduan bantuan Mode Spesifikasi-Pertama.

Mengapa Migrasi Stoplight Lebih dari Sekadar Impor OpenAPI

OpenAPI mendefinisikan kontrak API, tetapi proyek Stoplight biasanya menyimpan konteks tambahan di sekitar kontrak tersebut.

Struktur repositori yang umum:

api-project/
├── reference/
│   └── openapi.yaml
├── docs/
│   ├── getting-started.md
│   └── authentication.md
├── models/
│   └── error.json
├── images/
│   └── auth-flow.png
├── .stoplight.json
└── toc.json

Jika Anda hanya memindahkan openapi.yaml, risiko berikut dapat muncul:

• Dokumen Markdown tidak ikut termigrasi atau tautannya rusak.
• Struktur navigasi dari toc.json tidak sama.
• JSON Schema tidak lagi terhubung ke dokumentasi.
• Gambar lokal tidak dirender.
• Mock, pengujian, dan koleksi permintaan tetap tersebar di alat lain.

Karena itu, mulai migrasi dari pohon file dan repositori, bukan dari satu file OpenAPI.

---

Model Migrasi: Pindahkan, Tinjau, Bangun Kembali, Hubungkan

Sebelum migrasi, tentukan sumber kebenaran API Anda.

Jika OpenAPI di Git adalah kontrak utama, gunakan file tersebut sebagai pusat migrasi. Jika koleksi Postman atau Bruno justru menjadi definisi perilaku API sehari-hari, selesaikan ketidaksesuaian itu terlebih dahulu.

Gunakan empat kategori berikut:

Kategori	Isi	Tindakan
Pindahkan	OpenAPI, Markdown, gambar lokal, JSON Schema, .stoplight.json, dan toc.json yang didukung	Impor konteks proyek berbasis file ke Mode Spesifikasi-Pertama
Tinjau	Tautan, anchor, gambar, $ref, skema, TOC, ID Stoplight, dan perbedaan rendering	Validasi hasil sebelum digunakan di produksi
Bangun Kembali	Koleksi Postman/Bruno, environment, pengujian, mock, CI, dan proses publikasi	Bangun ulang di sekitar kontrak OpenAPI
Hubungkan	Dokumentasi, mock, pengujian, laporan, izin, dan kolaborasi	Jadikan kontrak API pusat alur kerja tim

Migrasi Stoplight memiliki dua lapisan:

1. Lapisan file: OpenAPI, Markdown, model, gambar, dan konfigurasi proyek.
2. Lapisan alur kerja: review perubahan, publikasi dokumentasi, mock, testing, CI, laporan, dan kolaborasi lintas tim.

Mode Spesifikasi-Pertama paling langsung membantu pada lapisan file. Setelah itu, gunakan Apidog untuk menghubungkan kontrak ke alur kerja API yang lebih luas.

---

Bagaimana Mode Spesifikasi-Pertama Apidog Cocok dengan Proyek Stoplight

Mode Spesifikasi-Pertama Apidog dirancang untuk alur kerja API berbasis file.

Anda dapat memilih dua pendekatan:

• Terhubung ke Git: repositori dan cabang tetap menjadi sumber kebenaran.
• Berbasis file: kelola file spesifikasi di Apidog terlebih dahulu, lalu hubungkan Git nanti.

Ruang kerja Spesifikasi menyediakan satu tempat untuk:

• Mengelola file sumber
• Melihat struktur API yang diurai
• Mengedit spesifikasi
• Meninjau perubahan
• Menyinkronkan perubahan ke repositori

Ruang kerja Spesifikasi memungkinkan tim mengelola file sumber, struktur API yang diurai, dan alur kerja pengeditan di satu tempat.

Pemetaan Aset Stoplight ke Apidog

Aset Stoplight	Perilaku di Apidog	Hal yang perlu ditinjau
File OpenAPI / Swagger	Dapat diimpor dan disinkronkan sebagai modul API, endpoint, skema, dan contoh	Periksa $ref, peringatan konversi, nama modul, dan pengelompokan endpoint
.stoplight.json	Bidang yang didukung dapat membantu menemukan akar OpenAPI, Markdown, JSON Schema, pola include/exclude, dan tocPath	Jangan mengasumsikan seluruh konfigurasi Stoplight dipetakan satu-per-satu
toc.json	Dapat membantu membuat folder DOCS, mengurutkan Markdown, menerapkan judul, menautkan modul OAS, dan mengimpor model yang direferensikan	Tinjau sidebar akhir karena model navigasi Apidog dapat berbeda
Markdown	Dokumentasi dapat dibawa ke alur kerja proyek	Periksa tautan internal, anchor, format, dan file yang hilang
Gambar lokal	Gambar yang direferensikan Markdown dapat diimpor jika didukung	Periksa gambar eksternal, URI data, referensi rusak, dan aset tidak terpakai
JSON Schema	Model yang secara eksplisit direferensikan oleh struktur proyek yang didukung dapat diimpor	Periksa nama, folder, format, dan referensi model
ID Stoplight	ID tingkat root dapat membantu pencocokan modul selama sinkronisasi	Jangan mengandalkan ID untuk semua jenis resource

Catatan Kompatibilitas untuk File Stoplight

.stoplight.json

Perlakukan .stoplight.json sebagai konfigurasi penemuan jalur yang didukung, bukan sebagai konfigurasi proyek Stoplight lengkap.

Bidang yang dapat digunakan mencakup:

• Direktori root OpenAPI, Markdown, dan JSON Schema yang didukung
• Pola penyertaan OpenAPI
• Pola pengecualian global
• tocPath

Selalu verifikasi output impor. Jangan mengasumsikan semua pengaturan formats atau perilaku Stoplight akan diterapkan dengan cara yang sama.

toc.json

toc.json dapat membantu mempertahankan struktur navigasi yang didukung, seperti:

• Folder DOCS
• Pengurutan dokumen Markdown
• Judul navigasi
• Tautan ke modul OAS
• Tautan ke item spesifikasi tertentu
• Model JSON Schema yang direferensikan TOC

Namun, sidebar akhir tetap dirender melalui model DOCS/OAS/MODELS Apidog. Pengurutan lintas tipe atau layout Stoplight yang sangat kustom mungkin tidak dipertahankan sepenuhnya.

Gambar dan Model

• Gambar paling dapat diprediksi saat direferensikan langsung oleh Markdown.
• Gambar eksternal, URI data, dan aset yang tidak direferensikan harus ditinjau terpisah.
• JSON Schema lebih mudah dipetakan ketika direferensikan secara eksplisit, misalnya melalui toc.json.
• Jangan berasumsi semua file JSON dalam direktori models/ otomatis menjadi resource model.

---

Dari Impor File ke Alur Kerja API Terhubung

Impor OpenAPI satu kali dapat menciptakan penyimpangan antara:

• File di Git
• Dokumentasi
• Ruang kerja API
• Pengujian
• Mock
• Proses CI

Mode Spesifikasi-Pertama menjaga file sebagai fondasi alur kerja.

Dalam proyek yang terhubung ke Git, tim dapat:

1. Mengedit file spesifikasi di ruang kerja Spesifikasi.
2. Meninjau perubahan.
3. Commit perubahan.
4. Push kembali ke repositori.

Dalam proyek berbasis file, tim dapat mengedit dan menyimpan spesifikasi di Apidog sebelum Git dihubungkan.

Gunakan pembagian tanggung jawab berikut:

Tanggung jawab	Sumber yang direkomendasikan
Kontrak API	File OpenAPI / Swagger
Struktur proyek	Repositori atau pohon file
Konfigurasi jalur Stoplight yang didukung	.stoplight.json
Navigasi dokumentasi	toc.json dan Markdown
Kolaborasi API harian	Ruang kerja proyek Apidog
Mock, testing, laporan, dan izin	Alur kerja platform Apidog

Pendekatan ini memindahkan lebih dari data. Anda mempertahankan kontrak berbasis file sekaligus membangun ruang kerja API di sekitarnya.

---

Jalur Migrasi Terhubung Git vs Berbasis File

Jalur	Cocok untuk	Alur kerja
Proyek Spesifikasi-Pertama terhubung Git	Tim yang sudah menyimpan OpenAPI di Git	Hubungkan repositori, sinkronkan cabang, edit file, commit, dan push
Proyek Spesifikasi-Pertama berbasis file	Tim yang ingin memvalidasi proses berbasis file terlebih dahulu	Kelola file di Apidog, simpan perubahan, lalu hubungkan Git saat siap

Untuk kebanyakan tim Stoplight, proyek terhubung Git adalah pilihan jangka panjang yang lebih jelas karena repositori tetap menjadi sumber kebenaran.

Pilih mode berbasis file jika Anda masih ingin:

• Mengevaluasi pengalaman editing
• Membersihkan struktur proyek
• Mempersiapkan migrasi
• Mengadopsi proses Git secara bertahap

---

Checklist Setelah Migrasi

Setelah membuat proyek Spesifikasi-Pertama, lakukan tinjauan berikut.

Area	Yang harus diperiksa
Modul OpenAPI	Pastikan semua spesifikasi diimpor, nama modul benar, dan endpoint dikelompokkan sesuai harapan
Referensi eksternal	Pastikan dependensi $ref terselesaikan dan periksa masalah konversi
Lint / validasi	Jalankan validasi Spesifikasi pada file OpenAPI yang diimpor
.stoplight.json	Verifikasi root OpenAPI, Markdown, JSON Schema, pola include/exclude, dan tocPath
toc.json	Periksa grup, judul, urutan Markdown, tautan OAS, model yang direferensikan, dan sidebar akhir
Markdown	Periksa heading, format, tautan relatif, anchor, dan tautan API
Gambar	Pastikan gambar lokal dirender; tinjau gambar eksternal, URI data, dan referensi rusak
Model	Pastikan model JSON Schema yang direferensikan memiliki nama, folder, dan referensi yang benar
ID Stoplight	Verifikasi perilaku pencocokan modul pada sinkronisasi berikutnya
Testing dan mock	Bangun ulang atau hubungkan skenario dari Postman, Bruno, CI, atau alat lain
Izin dan publikasi	Buat ulang akses tim, visibilitas dokumentasi, aturan review, dan tanggung jawab rilis

Untuk validasi berbasis Spectral, Apidog dapat menggunakan file berikut pada root proyek:

.spectral.yaml
.spectral.yml
.spectral.json
.spectral.mjs

Apidog juga dapat kembali ke:

.stoplight/styleguide.json

Gunakan hasil lint sebagai sinyal review. Keberhasilan validasi tidak berarti seluruh perilaku khusus Stoplight telah dipertahankan.

---

Bagaimana dengan Aset Postman dan Bruno?

Koleksi Postman dan file .bru Bruno bukan objek migrasi yang sama dengan spesifikasi OpenAPI.

OpenAPI mendefinisikan kontrak API, sedangkan koleksi biasanya berisi:

• Request contoh
• Environment
• Variabel
• Skrip pengujian
• Alur request manual
• Data autentikasi
• Otomasi CI

Sebelum memigrasikan aset tersebut, jawab pertanyaan berikut:

Pertanyaan	Mengapa penting
Apakah OpenAPI atau koleksi menjadi sumber kebenaran?	Migrasi harus dimulai dari kontrak yang berwenang
Request mana yang masih relevan?	Bangun ulang contoh penting di ruang kerja baru
Pengujian mana yang wajib terus berjalan?	Hubungkan kembali testing ke alur kerja baru
Environment dan rahasia mana yang dibagikan?	Rencanakan manajemen environment secara terpisah
Job CI mana yang bergantung pada alat lama?	Migrasikan validasi, testing, dan pelaporan dengan sengaja

Bagi pengguna Bruno, alur kerja Git-native tetap berharga. Namun, aset Bruno mungkin masih memerlukan migrasi, pembangunan ulang, atau penggantian terpisah berdasarkan cara tim menggunakannya.

---

Rencana Migrasi yang Direkomendasikan

Gunakan migrasi bertahap. Jangan mencoba memindahkan seluruh alur kerja sekaligus.

Rencana migrasi bertahap: pindahkan kontrak OpenAPI terlebih dahulu, lalu hubungkan kembali alur kerja di sekitarnya.

1. Audit repositori bergaya Stoplight

Inventarisasi file berikut:

OpenAPI / Swagger
.stoplight.json
toc.json
Markdown
JSON Schema
Gambar lokal
Koleksi Postman atau Bruno
Skrip pengujian
Konfigurasi CI

2. Putuskan sumber kebenaran

Konfirmasikan bahwa OpenAPI di Git adalah kontrak utama.

Jika koleksi Postman atau Bruno lebih akurat daripada OpenAPI, perbaiki perbedaan tersebut sebelum memulai migrasi.

3. Buat proyek Spesifikasi-Pertama

Pilih:

• Terhubung Git jika Git harus tetap menjadi sumber kebenaran.
• Berbasis file jika Anda ingin memvalidasi proses sebelum menghubungkan repositori.

4. Tinjau aset yang berhasil dipindahkan

Periksa:

• Modul OpenAPI
• Dokumentasi Markdown
• Model
• Gambar yang direferensikan
• Tautan dan anchor
• Input navigasi toc.json
• Konfigurasi jalur .stoplight.json
• Hasil validasi spesifikasi

Jika ada masalah, perbaiki file sumber bila memungkinkan. Hindari menambal gejala secara manual di banyak tempat.

5. Bangun kembali aset tingkat alur kerja

Hubungkan kembali:

• Mock
• Pengujian
• Request contoh
• Job CI
• Laporan
• Izin tim
• Aturan publikasi

6. Jalankan perubahan nyata pertama

Buat perubahan kecil pada OpenAPI, lalu:

1. Review perubahan.
2. Sinkronkan file.
3. Perbarui dokumentasi bila diperlukan.
4. Jalankan validasi.
5. Uji mock dan test scenario.
6. Verifikasi laporan downstream.

Langkah ini membuktikan bahwa alur kerja baru benar-benar berfungsi, bukan hanya berhasil mengimpor file.

---

Kapan Jalur Migrasi Ini Cocok?

Gunakan jalur ini jika:

• Tim menyimpan OpenAPI atau Swagger sebagai file.
• Proyek Stoplight berisi Markdown, model, gambar, .stoplight.json, atau toc.json.
• Review API sudah menggunakan branch Git atau pull request.
• Dokumentasi, mock, testing, laporan, dan kolaborasi perlu tetap terhubung ke kontrak.
• Anda ingin mengurangi penyimpangan antara file API dan workspace yang dipakai frontend, QA, produk, platform, atau mitra.

Rencanakan lebih hati-hati jika:

• Sumber kebenaran sebenarnya adalah koleksi Postman atau Bruno.
• Proyek sangat bergantung pada perilaku publikasi Stoplight yang kustom.
• Dokumentasi memiliki banyak tautan eksternal, anchor, halaman yang dihasilkan, atau aset tidak direferensikan.
• JSON Schema menggunakan struktur yang membutuhkan review manual.
• Tim mengharapkan reproduksi navigasi atau rendering Stoplight yang identik piksel demi piksel.

---

FAQ

Apakah Mode Spesifikasi-Pertama Apidog merupakan alternatif Stoplight?

Ya, untuk tim yang ingin mempertahankan proyek OpenAPI berbasis file sambil menambahkan dokumentasi, mock, pengujian, laporan, izin, dan kolaborasi di sekitar kontrak API.

Dapatkah saya menyimpan spesifikasi OpenAPI di Git?

Ya. Dalam proyek yang terhubung Git, tim dapat menyinkronkan branch, mengedit file, melakukan commit, dan push perubahan kembali ke repositori.

Apakah Git diperlukan untuk memulai?

Tidak. Anda dapat menggunakan proyek Spesifikasi-Pertama berbasis file dan menghubungkan Git kemudian.

Apakah .stoplight.json dan toc.json dipertahankan sepenuhnya?

Tidak. Apidog menggunakan bagian yang didukung sebagai input migrasi.

• .stoplight.json terutama membantu penemuan jalur, termasuk root OpenAPI, Markdown, JSON Schema, pola include/exclude, dan tocPath.
• toc.json dapat membantu membangun DOCS, tautan OAS/modul, tautan item spesifikasi, dan model yang direferensikan TOC.

Sidebar dokumentasi akhir tetap mengikuti model DOCS/OAS/MODELS Apidog.

Apa yang terjadi pada dokumen Markdown?

Markdown dapat dibawa ke proyek Spesifikasi-Pertama. Jika toc.json tersedia, struktur dokumen yang terdaftar dapat dipertahankan sejauh didukung.

Tetap periksa tautan internal, anchor, gambar, dan perbedaan rendering.

Apa yang terjadi pada JSON Schema?

Model JSON Schema dapat dipindahkan jika didukung dan direferensikan secara eksplisit oleh struktur proyek, seperti toc.json.

Jangan mengasumsikan setiap file JSON dalam direktori model akan otomatis diimpor. Periksa format, nama, folder, dan referensi setelah migrasi.

Apa yang terjadi pada gambar?

Gambar lokal yang direferensikan oleh Markdown dapat diimpor jika didukung.

Jangan memperlakukan formats.image.rootDir sebagai jaminan semua file gambar akan diimpor. Tinjau gambar eksternal, URI data, referensi rusak, dan aset tidak terpakai secara terpisah.

Haruskah saya menjalankan lint atau validasi setelah migrasi?

Ya. Jalankan validasi Spesifikasi pada OpenAPI yang diimpor.

Apidog dapat membaca .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs, atau menggunakan .stoplight/styleguide.json sebagai fallback untuk validasi editor berbasis Spectral.

Gunakan hasil validasi untuk meninjau masalah kontrak dan gaya, bukan sebagai bukti bahwa seluruh perilaku Stoplight dipertahankan.

Apa yang harus dilakukan pengguna Bruno atau Postman?

Tentukan lebih dahulu apakah OpenAPI atau koleksi yang menjadi sumber kebenaran.

Migrasi Spesifikasi-Pertama berpusat pada OpenAPI dan file proyek terkait. Koleksi, environment, dan pengujian berbasis request mungkin memerlukan migrasi atau pembangunan ulang terpisah.

Apakah Apidog mendukung mock, pengujian, CI/CD, laporan, dan kolaborasi?

Ya. Mode Spesifikasi-Pertama menghubungkan kontrak API berbasis file ke Apidog. Platform Apidog yang lebih luas dapat mendukung dokumentasi, mock, skenario testing, eksekusi CI/CD dengan Apidog CLI, laporan, izin, dan kolaborasi tim.

---

Kesimpulan

Migrasi Stoplight tidak harus berarti meninggalkan alur kerja API berbasis file.

Repositori dapat tetap menjadi sumber kebenaran. File OpenAPI, dokumentasi Markdown, gambar yang direferensikan, JSON Schema yang direferensikan TOC, dan konfigurasi proyek yang didukung tetap dapat dipindahkan dan ditinjau.

Pendekatan yang paling aman adalah:

1. Audit struktur repositori.
2. Tentukan sumber kebenaran kontrak API.
3. Pindahkan aset berbasis file yang didukung.
4. Tinjau hasil migrasi.
5. Bangun ulang aset tingkat alur kerja.
6. Validasi perubahan nyata pertama dari awal hingga akhir.

Mode Spesifikasi-Pertama Apidog menyediakan jalur praktis untuk menjaga kontrak API tetap berbasis file sambil menghubungkannya ke dokumentasi, mock, testing, laporan, izin, dan kolaborasi.

Untuk perencanaan migrasi perusahaan, lihat Apidog Enterprise.