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

Migrasi dari Stoplight ke Apidog bukan hanya tentang mengimpor file OpenAPI. Ini adalah tentang transisi alur kerja API berbasis file.

Bagi banyak tim, proyek Stoplight mencakup lebih dari sekadar endpoint: spesifikasi OpenAPI di Git, dokumen Markdown, model JSON Schema, gambar lokal, input navigasi toc.json yang didukung, dan pengaturan jalur .stoplight.json yang didukung.

Sebuah tim mungkin juga memiliki contoh permintaan di Postman dan skrip pengujian di CI. Jika migrasi Stoplight ke Apidog hanya mengimpor satu file OpenAPI, daftar endpoint mungkin tetap ada, tetapi alur kerjanya tidak.

Mode Spesifikasi-Pertama Apidog membantu tim menjaga file OpenAPI sebagai sumber kebenaran selama migrasi Stoplight sambil menghubungkan file-file tersebut ke ruang kerja API yang lebih luas untuk dokumen, mock, pengujian, laporan, izin, dan kolaborasi.

Panduan ini menjelaskan cara merencanakan migrasi tersebut: apa yang dapat dipindahkan, apa yang harus ditinjau, apa yang perlu dibangun kembali, dan apa yang harus dihubungkan di sekitar kontrak OpenAPI.

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

Mengapa Migrasi Stoplight Lebih dari Sekadar Impor OpenAPI

Sebuah file OpenAPI menjelaskan kontrak API. Proyek bergaya Stoplight biasanya berisi lebih banyak konteks di sekitar kontrak tersebut.

Aset proyek umum meliputi:

File OpenAPI atau Swagger, sering disimpan di bawah reference atau direktori lain yang dikonfigurasi;
Dokumentasi Markdown, sering disimpan di bawah docs;
File model JSON Schema, sering disimpan di bawah models;
Gambar lokal yang direferensikan oleh dokumentasi;
.stoplight.json untuk konfigurasi jalur yang didukung;
toc.json untuk input navigasi dokumentasi yang didukung, pengelompokan, dan urutan;
Identifikasi Stoplight seperti x-stoplight-id atau x-stoplight.id.

Jika migrasi hanya mengimpor satu file OpenAPI, endpoint mungkin berpindah, tetapi model proyek masih bisa hilang. Dokumentasi mungkin perlu dibangun kembali. Navigasi mungkin tidak cocok dengan proyek sebelumnya. Model mungkin terputus dari dokumentasi. Pengujian, mock, dan contoh permintaan mungkin masih berada di alat yang terpisah.

Rencana migrasi yang lebih baik dimulai dari repositori atau pohon file, bukan dari satu file spesifikasi.

Model Migrasi: Pindahkan, Tinjau, Bangun Kembali, Hubungkan

Sebelum memulai, identifikasi sumber kebenaran yang sebenarnya. Jika file OpenAPI di Git mendefinisikan kontrak API, migrasi Spesifikasi-Pertama dapat dimulai dari file-file tersebut. Jika koleksi Postman atau Bruno mendorong alur kerja permintaan yang sebenarnya, selesaikan ketidaksesuaian itu terlebih dahulu.

Rencana migrasi terkuat bukanlah "pertahankan semuanya." Proyek Stoplight dapat berisi perilaku spesifik produk yang tidak dapat dipetakan satu-per-satu ke ruang kerja lain.

Gunakan model empat bagian sebagai gantinya:

Kategori	Apa yang termasuk di sini	Sikap Migrasi
Pindahkan	File OpenAPI, pengaturan jalur `.stoplight.json` yang didukung, input navigasi `toc.json` yang didukung, dokumen Markdown, gambar lokal yang direferensikan, dan model JSON Schema jika didukung.	Bawa konteks proyek berbasis file ke dalam Mode Spesifikasi-Pertama.
Tinjau	Tautan Markdown, anchor, gambar, pengelompokan TOC, penamaan skema, `$ref` eksternal, ID Stoplight, halaman yang dihasilkan, dan perbedaan rendering.	Verifikasi ruang kerja yang dimigrasi sebelum menganggapnya siap produksi.
Bangun Kembali	Alur permintaan Postman atau Bruno, lingkungan, pengujian manual, mock, pekerjaan CI, dan aturan publikasi jika berada di luar proyek spesifikasi.	Buat kembali ini di sekitar sumber kebenaran OpenAPI.
Hubungkan	Dokumen API, API mock, pengujian, laporan CI, izin, kolaborasi tim, dan alur kerja yang menghadap mitra.	Gunakan Apidog untuk membuat kontrak berguna di seluruh siklus hidup API.

Perbedaan ini penting karena migrasi Stoplight memiliki dua lapisan.

Lapisan pertama adalah lapisan file: spesifikasi OpenAPI, dokumen Markdown, file model, gambar, dan file struktur proyek. Di sinilah Mode Spesifikasi-Pertama paling langsung berguna.

Lapisan kedua adalah lapisan alur kerja: bagaimana tim Anda meninjau perubahan API, memublikasikan dokumentasi, menjalankan pengujian, mengelola mock, membagikan laporan, dan berkolaborasi di seluruh tim backend, frontend, QA, produk, dan mitra. Lapisan ini tidak boleh diperlakukan sebagai produk sampingan dari impor. Di sinilah Apidog dapat menghubungkan kontrak ke sisa siklus hidup API.

Bagaimana Mode Spesifikasi-Pertama Apidog Cocok dengan Proyek Stoplight

Mode Spesifikasi-Pertama Apidog dibangun untuk alur kerja berbasis file—persis seperti yang sudah digunakan oleh proyek Stoplight Anda.

Proyek yang terhubung dengan Git menjaga repositori Anda di pusat. Cabang Anda tetap menjadi sumber kebenaran, dan Apidog menyinkronkannya.

Proyek berbasis file memungkinkan Anda bekerja dengan file spesifikasi langsung di Apidog terlebih dahulu. Anda dapat menghubungkan Git nanti saat Anda siap.

Ruang kerja Spesifikasi memberi Anda satu tempat untuk mengelola file sumber Anda, melihat struktur API yang diurai, dan menangani semua alur kerja pengeditan Anda.

Ruang kerja Spesifikasi Apidog untuk mengelola file OpenAPI dalam Mode Spesifikasi-Pertama — Ruang kerja Spesifikasi memungkinkan tim mengelola file sumber, struktur API yang diurai, dan alur kerja pengeditan di satu tempat.

Berikut adalah cara setiap jenis aset Stoplight berfungsi di Apidog:

Aset Stoplight	Apa yang Terjadi di Apidog	Catatan Ulasan
File OpenAPI / Swagger	Dapat diimpor dan disinkronkan sebagai modul API, endpoint, skema, dan contoh.	Tinjau referensi yang dibundel, peringatan konversi, penamaan modul, dan pengelompokan endpoint.
`.stoplight.json`	Bidang yang didukung dapat membantu Apidog menemukan akar OpenAPI, Markdown, dan JSON Schema, menerapkan pola penyertaan OpenAPI, menerapkan pola pengecualian global, dan menyelesaikan `tocPath`.	Perlakukan itu sebagai penemuan jalur untuk sinkronisasi, bukan konfigurasi proyek Stoplight lengkap. Jangan berasumsi semua pengaturan `formats` Stoplight atau perilaku proyek diterapkan dengan cara yang sama.
`toc.json`	Dapat membantu Apidog membuat folder DOCS dari grup dan pembatas yang didukung, menyaring dan mengurutkan dokumen Markdown yang terdaftar di TOC, menerapkan judul TOC, menautkan folder DOCS ke modul OAS yang diimpor atau item spesifikasi yang dipilih, dan mengimpor model JSON Schema yang direferensikan TOC jika didukung.	Tinjau bilah sisi Apidog akhir setelah impor. Struktur akhir dirender melalui model DOCS/OAS/MODELS Apidog, sehingga navigasi Stoplight yang tepat atau pengurutan lintas-tipe yang sewenang-wenang mungkin tidak dipertahankan.
Dokumen Markdown	Dokumentasi Markdown dapat dibawa ke alur kerja proyek. Dokumen yang terdaftar di TOC dapat mempertahankan lebih banyak struktur jika didukung.	Tinjau tautan internal, anchor, pemformatan, file yang hilang, dan perbedaan rendering.
Gambar Lokal	Gambar lokal yang direferensikan oleh Markdown dapat diimpor jika didukung.	Tinjau referensi yang rusak, gambar eksternal, URI data, dan gambar yang tidak direferensikan oleh dokumen. Jangan memperlakukan pengaturan akar gambar sebagai jaminan impor pustaka aset.
Model JSON Schema	File JSON Schema yang secara eksplisit direferensikan oleh struktur proyek yang didukung, seperti `toc.json`, dapat dibawa ke Model jika didukung.	Tinjau format skema, penamaan, pengelompokan, referensi, dan apakah setiap model harus diimpor.
ID Stoplight	ID Stoplight tingkat root dapat membantu Apidog mencocokkan modul yang diimpor di seluruh sinkronisasi.	Jangan berasumsi identitas tingkat endpoint atau tingkat halaman sepenuhnya dipertahankan.

Catatan Kompatibilitas untuk File Proyek Stoplight

.stoplight.json harus diperlakukan sebagai subset konfigurasi jalur yang didukung untuk sinkronisasi. Apidog dapat menggunakan direktori root yang didukung untuk OpenAPI, Markdown, dan JSON Schema, pola penyertaan OpenAPI, pola pengecualian global, dan tocPath. Pengaturan proyek Stoplight lainnya harus diperlakukan sebagai diabaikan kecuali diverifikasi.
toc.json dapat membantu membangun kembali semantik navigasi yang didukung di Apidog, termasuk folder DOCS, pengurutan Markdown, tautan OAS/modul, tautan item spesifikasi yang dipilih, dan impor model yang direferensikan TOC. Bilah sisi akhir masih dirender melalui model DOCS/OAS/MODELS Apidog, sehingga tata letak Stoplight yang sewenang-wenang dan pengurutan lintas-tipe yang tepat mungkin tidak dipertahankan. toc.json tidak sepenuhnya menyesuaikan bilah sisi dokumentasi online akhir.
Gambar terutama dimigrasi ketika direferensikan oleh Markdown. Aset yang tidak direferensikan, gambar eksternal, dan URI data harus ditinjau secara terpisah.
File JSON Schema paling dapat diprediksi ketika secara eksplisit direferensikan oleh struktur proyek yang didukung, seperti toc.json, daripada diasumsikan hanya dari direktori.

Ini memberi tim titik awal yang praktis: gunakan file proyek yang ada untuk membuat ulang sebanyak mungkin ruang kerja API, lalu tinjau bagian-bagian yang bergantung pada perilaku spesifik Stoplight. Tujuannya bukan untuk membuat ulang Stoplight pixel demi pixel, tetapi untuk mempertahankan konteks proyek berbasis file yang portabel dan menghubungkannya kembali ke siklus hidup API yang lebih luas.

Dari Impor File ke Alur Kerja API Terhubung

Dalam alur kerja impor tradisional, tim sering mengimpor file OpenAPI sekali dan kemudian melanjutkan bekerja secara visual di alat baru. Hal itu dapat menciptakan penyimpangan: file di Git, dokumentasi, dan ruang kerja API mungkin tidak lagi mewakili sumber kebenaran yang sama.

Mode Spesifikasi-Pertama berbeda. File-file tetap menjadi fondasi.

Dalam proyek Spesifikasi-Pertama yang terhubung dengan Git, tim dapat mengedit file di ruang kerja Spesifikasi, lalu melakukan commit dan push perubahan kembali ke repositori. Dalam proyek berbasis file, tim dapat mengedit dan menyimpan file spesifikasi di dalam Apidog sebelum menghubungkan Git.

Pembagian praktisnya adalah:

Tanggung Jawab	Sumber yang Direkomendasikan
Kontrak API	File OpenAPI / Swagger
Struktur file proyek	Repositori atau pohon proyek berbasis file
Pengaturan jalur bergaya Stoplight yang didukung	`.stoplight.json`
Input navigasi dokumentasi yang didukung	`toc.json` dan dokumen Markdown
Kolaborasi API harian	Ruang kerja proyek Apidog
Mock, pengujian, laporan, dan izin tim	Alur kerja platform Apidog yang lebih luas

Ini adalah nilai inti migrasi: tim dapat mempertahankan model kontrak berbasis file-pertama sambil memberikan lebih banyak pemangku kepentingan ruang kerja API yang dapat digunakan di sekitar kontrak tersebut.

Itulah perbedaan antara memindahkan data dan memindahkan alur kerja. Mengimpor file memindahkan kontrak sekali. Menghubungkan proyek Spesifikasi-Pertama memberi tim ruang kerja di sekitar kontrak.

Jalur Migrasi Terhubung-Git vs Berbasis-File

Tim Stoplight tidak semua memulai dari kematangan alur kerja yang sama.

Beberapa tim sudah meninjau setiap perubahan API melalui cabang Git dan pull request. Yang lain memiliki spesifikasi API dan dokumen sebagai file, tetapi belum siap untuk menjadikan penyedia Git eksternal sebagai bagian dari peluncuran pertama.

Mode Spesifikasi-Pertama Apidog mendukung kedua jalur.

Jalur	Terbaik untuk	Alur kerja umum
Proyek Spesifikasi-Pertama terhubung Git	Tim yang sudah mengelola spesifikasi OpenAPI di Git.	Hubungkan repositori, sinkronkan cabang, edit file, commit, dan push.
Proyek Spesifikasi-Pertama berbasis file	Tim yang menginginkan desain API berbasis file sebelum menghubungkan Git.	Kerjakan file spesifikasi di Apidog, simpan perubahan, dan validasi alur kerja terlebih dahulu.

Untuk sebagian besar migrasi Stoplight, proyek yang terhubung dengan Git adalah model jangka panjang yang lebih jelas karena repositori tetap menjadi sumber kebenaran kontrak.

Proyek berbasis file berguna ketika tim ingin mengevaluasi pengalaman penulisan, membersihkan file proyek, atau menyiapkan migrasi sebelum mengadopsi alur kerja Git yang lebih ketat.

Apa yang Harus Ditinjau Setelah Migrasi

Meskipun file proyek dapat dipindahkan, migrasi harus mencakup tinjauan. Ini sangat penting untuk tim dengan situs dokumentasi besar, banyak file skema, atau navigasi Stoplight yang disesuaikan.

Gunakan daftar periksa ini setelah membuat proyek Spesifikasi-Pertama.

Area	Apa yang harus diperiksa
Modul OpenAPI	Konfirmasikan semua file spesifikasi yang dimaksudkan diimpor, nama modul benar, dan endpoint dikelompokkan seperti yang diharapkan.
Referensi eksternal	Periksa apakah dependensi `$ref` diselesaikan seperti yang diharapkan dan apakah ada masalah konversi yang dilaporkan.
Lint / validasi	Jalankan validasi Spesifikasi Apidog pada file OpenAPI yang diimpor. Apidog dapat menggunakan `.spectral.yaml`, `.spectral.yml`, `.spectral.json`, `.spectral.mjs` tingkat root, dan dapat kembali ke `.stoplight/styleguide.json` untuk validasi editor berbasis Spectral. Perlakukan temuan sebagai sinyal tinjauan, bukan sebagai migrasi tata kelola panduan gaya Stoplight penuh.
`.stoplight.json`	Konfirmasikan akar OpenAPI, Markdown, dan JSON Schema yang didukung, pola penyertaan OpenAPI, pola pengecualian global, dan `tocPath`. Konfirmasikan output impor aktual daripada berasumsi setiap bidang konfigurasi Stoplight diterapkan.
`toc.json`	Tinjau grup yang didukung, pembatas, judul, pemfilteran dan pengurutan Markdown, grup yang dapat diklik, tautan OAS/modul, tautan item spesifikasi yang dipilih, impor model yang direferensikan TOC, dan output bilah sisi Apidog akhir.
Dokumen Markdown	Periksa pemformatan, judul, tautan relatif, anchor, dan tautan ke file atau operasi API.
Gambar	Konfirmasikan gambar lokal yang direferensikan dirender dengan benar. Tinjau gambar eksternal, URI data, referensi yang rusak, dan aset yang tidak digunakan secara terpisah.
Model	Konfirmasikan file JSON Schema yang direferensikan `toc.json` mana yang menjadi sumber daya model dan apakah nama, folder, dan referensinya benar.
ID Stoplight	Konfirmasikan pencocokan modul berperilaku seperti yang diharapkan di seluruh sinkronisasi berulang. Jangan hanya mengandalkan ID untuk setiap jenis sumber daya.
Pengujian dan mock	Bangun kembali atau hubungkan kembali skenario yang sebelumnya dikelola di Postman, Bruno, CI, atau alat terpisah.
Izin dan publikasi	Buat ulang akses tim, visibilitas dokumentasi, aturan tinjauan, dan tanggung jawab rilis di ruang kerja baru.

Tinjauan ini bukanlah solusi sementara. Ini adalah perbedaan normal antara memindahkan file dan memindahkan seluruh pengalaman spesifik produk.

Bagaimana dengan Aset Postman dan Bruno?

Banyak tim Stoplight juga menggunakan Postman atau Bruno. Aset-aset tersebut harus direncanakan secara terpisah dari migrasi OpenAPI.

File OpenAPI mendefinisikan kontrak API. Koleksi Postman dan file .bru Bruno biasanya mendefinisikan alur kerja permintaan, contoh, lingkungan, atau pengujian. Ini bisa berharga, tetapi bukan objek migrasi yang sama dengan proyek OpenAPI bergaya Stoplight.

Sebelum migrasi, jawab pertanyaan-pertanyaan ini:

Pertanyaan	Mengapa ini penting
Apakah OpenAPI sumber kebenaran, ataukah koleksi yang mendorong perilaku API sebenarnya?	Migrasi Spesifikasi-Pertama harus dimulai dari kontrak yang berwenang.
Contoh permintaan mana yang masih penting?	Bangun kembali contoh penting di sekitar ruang kerja API yang terhubung.
Pengujian mana yang harus terus berjalan?	Pindahkan atau hubungkan kembali pengujian API ke alur kerja baru alih-alih berasumsi bahwa mereka bermigrasi dengan dokumen.
Lingkungan dan rahasia mana yang dibagikan?	Rencanakan manajemen lingkungan secara terpisah dari migrasi spesifikasi.
Pekerjaan CI mana yang bergantung pada alat saat ini?	Hubungkan kembali validasi, pengujian, dan pelaporan secara sengaja.

Bagi pengguna Bruno, wawasan kuncinya adalah bahwa alur kerja asli Git sudah berharga. Mode Spesifikasi-Pertama dapat menjaga kontrak berbasis file, tetapi aset Bruno mungkin masih memerlukan migrasi, pembangunan kembali, atau penggantian terpisah tergantung pada bagaimana tim menggunakannya.

Rencana Migrasi yang Direkomendasikan

Gunakan rencana bertahap daripada mencoba memindahkan setiap alur kerja API sekaligus.

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

1. Audit repositori bergaya Stoplight

Identifikasi file OpenAPI, .stoplight.json, toc.json, dokumen Markdown, model, gambar, dan aset permintaan atau pengujian terkait lainnya.

2. Putuskan sumber kebenaran

Konfirmasikan apakah file OpenAPI di Git adalah sumber kontrak. Jika alat atau koleksi lain secara efektif adalah sumber kebenaran, selesaikan hal itu sebelum migrasi.

3. Buat proyek Spesifikasi-Pertama

Pilih proyek yang terhubung dengan Git jika tim siap untuk menjadikan Git sebagai sumber kebenaran. Pilih proyek berbasis file jika tim ingin memvalidasi alur kerja file terlebih dahulu.

4. Tinjau apa yang telah dipindahkan

Periksa modul, dokumen, model, gambar yang direferensikan, tautan, input navigasi toc.json yang didukung, pengaturan jalur .stoplight.json yang didukung, dan hasil validasi Spesifikasi. Perbaiki file proyek jika memungkinkan daripada menambal gejala secara manual.

5. Bangun kembali aset tingkat alur kerja

Hubungkan kembali mock, pengujian, contoh permintaan, pekerjaan CI, laporan, izin, dan tanggung jawab publikasi di sekitar kontrak API yang dimigrasi.

6. Jalankan perubahan nyata pertama melalui alur kerja baru

Buat perubahan OpenAPI kecil, tinjau, sinkronkan, perbarui dokumentasi jika diperlukan, dan validasi bahwa mock, pengujian, dan laporan downstream berperilaku seperti yang diharapkan.

Jika tim Anda sudah mengelola file OpenAPI, dokumen Markdown, dan model skema di repositori bergaya Stoplight, Mode Spesifikasi-Pertama Apidog dapat membantu Anda menguji jalur migrasi sebelum membangun kembali alur kerja penuh.

Kapan Jalur Migrasi Ini Paling Cocok

Jalur migrasi ini sangat cocok ketika:

tim Anda mengelola spesifikasi OpenAPI atau Swagger sebagai file;
proyek Stoplight Anda mencakup dokumen Markdown, model, gambar, .stoplight.json, atau toc.json;
proses tinjauan API Anda sudah bergantung pada cabang Git atau pull request;
Anda ingin dokumen API, mock, pengujian, laporan, dan kolaborasi tetap terhubung dengan kontrak;
Anda ingin mengurangi penyimpangan antara file API dan ruang kerja yang digunakan oleh tim frontend, QA, produk, platform, atau mitra.

Ini mungkin memerlukan lebih banyak perencanaan ketika:

sumber kebenaran API yang sebenarnya adalah koleksi Postman atau Bruno daripada OpenAPI;
proyek Stoplight sangat bergantung pada perilaku publikasi kustom;
dokumentasi berisi banyak tautan eksternal, anchor, halaman yang dihasilkan, atau aset yang tidak direferensikan;
model JSON Schema disimpan dalam format atau struktur yang memerlukan tinjauan manual;
tim menginginkan rekreasi navigasi Stoplight atau rendering dokumentasi yang sempurna piksel.

FAQ

Apakah Mode Spesifikasi-Pertama Apidog merupakan alternatif Stoplight?

Ini dapat digunakan sebagai alternatif Stoplight untuk tim yang ingin menjaga proyek OpenAPI berbasis file sambil menambahkan kolaborasi API yang lebih luas, pengujian, mocking, dokumentasi, pelaporan, dan manajemen izin di sekitar file-file tersebut.

Dapatkah saya menyimpan spesifikasi OpenAPI di Git?

Ya. Dalam proyek Spesifikasi-Pertama yang terhubung dengan Git, tim dapat menjaga Git sebagai sumber kebenaran, menyinkronkan cabang, mengedit file, dan melakukan commit perubahan kembali ke repositori.

Apakah saya memerlukan Git untuk memulai?

Tidak. Proyek Spesifikasi-Pertama berbasis file dapat digunakan ketika tim ingin bekerja dengan file spesifikasi terlebih dahulu dan menghubungkan Git nanti.

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

Tidak. Apidog menggunakan bagian-bagian yang didukung dari file-file ini sebagai input migrasi. .stoplight.json digunakan terutama untuk penemuan jalur selama sinkronisasi, termasuk akar OpenAPI, Markdown, JSON Schema yang didukung, pola penyertaan OpenAPI, pengecualian global, dan tocPath. toc.json dapat membantu mengatur konten DOCS yang didukung, tautan OAS/modul, tautan item spesifikasi yang dipilih, dan impor model yang direferensikan TOC. Bilah sisi dokumentasi online akhir masih dibatasi oleh model DOCS/OAS/MODELS Apidog, sehingga navigasi Stoplight yang tepat dan pengurutan lintas-tipe yang sewenang-wenang mungkin tidak dipertahankan.

Apa yang terjadi pada dokumen Markdown?

Dokumen Markdown dapat dibawa ke alur kerja proyek Spesifikasi-Pertama. Ketika toc.json ada, dokumen yang terdaftar di TOC dapat mempertahankan lebih banyak strukturnya jika didukung. Tautan internal, anchor, gambar, dan rendering harus tetap ditinjau.

Apa yang terjadi pada model JSON Schema?

Model JSON Schema dapat dipindahkan jika didukung ketika secara eksplisit direferensikan oleh struktur proyek yang didukung, seperti toc.json. Jangan berasumsi setiap file JSON di bawah direktori model akan secara otomatis menjadi sumber daya model. Tinjau format skema, 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 bahwa setiap file gambar di direktori tersebut akan diimpor. Gambar eksternal, URI data, referensi yang rusak, dan file gambar yang tidak digunakan harus diperiksa secara terpisah.

Haruskah saya menjalankan lint atau validasi setelah migrasi?

Ya. Setelah migrasi, jalankan validasi Spesifikasi pada file OpenAPI yang diimpor. Apidog mendukung validasi editor berbasis Spectral dan dapat membaca .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs tingkat root, atau kembali ke .stoplight/styleguide.json. Gunakan hasilnya untuk meninjau masalah kontrak dan gaya; jangan menganggap keberhasilan validasi sebagai bukti bahwa setiap perilaku spesifik Stoplight dipertahankan.

Apa yang harus dilakukan pengguna Bruno atau Postman?

Pertama, identifikasi apakah OpenAPI atau koleksi adalah sumber kebenaran. Migrasi Spesifikasi-Pertama berpusat pada OpenAPI dan file proyek terkait. Alur kerja permintaan berbasis koleksi, lingkungan, dan pengujian mungkin memerlukan migrasi atau pembangunan kembali terpisah.

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

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

Kesimpulan

Migrasi Stoplight seharusnya tidak berarti menyerah pada pekerjaan API berbasis file.

Repositori dapat tetap menjadi sumber kebenaran. Spesifikasi OpenAPI, dokumen Markdown, gambar yang direferensikan, model JSON Schema yang direferensikan TOC, dan file struktur proyek yang didukung dapat tetap portabel dan dapat ditinjau. Pada saat yang sama, alur kerja API di sekitar file-file tersebut dapat menjadi lebih terhubung.

Mode Spesifikasi-Pertama Apidog memberi tim Stoplight jalur migrasi praktis: pindahkan bagian-bagian proyek berbasis file jika didukung, tinjau struktur spesifik Stoplight dengan cermat, dan bangun kembali aset tingkat alur kerja di sekitar ruang kerja API yang terhubung.

Jika tim Anda sedang mengevaluasi migrasi Stoplight, mulailah dengan mengaudit struktur repositori Anda dan memutuskan file mana yang mendefinisikan kontrak API. Kemudian gunakan Mode Spesifikasi-Pertama untuk menghubungkan file-file tersebut ke dokumen, mock, pengujian, laporan, izin, dan kolaborasi di Apidog.

Untuk perencanaan migrasi perusahaan, lihat Apidog Enterprise.