Cara Migrasi dari Stoplight ke Apidog (Alur Kerja Berbasis Spesifikasi)

Jika Anda beralih dari Stoplight Studio atau Stoplight Platform ke Apidog, hal pertama yang perlu diketahui adalah Anda tidak perlu mengunggah ulang spesifikasi OpenAPI Anda. Mode Spec-First Apidog (saat ini dalam versi beta) terhubung langsung ke repo GitHub atau GitLab Anda yang sudah ada, sehingga Git tetap menjadi sumber kebenaran dan riwayat commit Anda tetap utuh. Panduan ini menjelaskan setiap langkah: mengekspor konfigurasi Stoplight Anda, memetakan konvensi direktorinya ke harapan Apidog, dan mengganti .stoplight.json serta toc.json dengan padanan Apidog mereka.

Tim seperti yang ada di Forum Ekonomi Dunia telah mengelola spesifikasi OpenAPI di Git bersama Stoplight untuk dokumentasi. Jika ini menggambarkan penyiapan Anda, panduan ini ditulis untuk Anda. Dan jika Anda masih mempertimbangkan pilihan daripada berkomitmen untuk migrasi, postingan alternatif Stoplight Studio teratas mencakup gambaran yang lebih luas.

Apa yang tetap sama saat Anda bermigrasi

File OpenAPI Anda, repo Git Anda, dan strategi cabang Anda tidak berubah. Itu adalah premis utamanya. Stoplight menyimpan spesifikasi sebagai file YAML atau JSON yang diperiksa ke dalam kontrol sumber. Apidog membaca file yang sama saat Anda menghubungkan repo dalam Mode Spec-First.

Yang berubah adalah semua yang berlapis di atasnya: perender dokumentasi, server mock, penjalur pengujian, dan klien API. Alih-alih Stoplight Platform menyajikan dokumen dan Postman menangani pengujian sebagai alat terpisah, Apidog menggabungkan semua itu dalam satu ruang kerja, disinkronkan dengan file OpenAPI yang sama yang sudah di-commit oleh para insinyur Anda.

Intinya: migrasi Anda sebagian besar adalah pertukaran konfigurasi, bukan migrasi data.

Langkah 1: Ekspor aset proyek Stoplight Anda

Sebelum menyentuh Apidog, tangkap semua yang dimiliki Stoplight yang belum ada di Git.

Jika Anda menggunakan Stoplight Studio dengan backend Git:

Spesifikasi OpenAPI Anda, model Skema JSON, dan dokumentasi Markdown sudah di-commit. Jalankan git pull untuk memastikan clone lokal Anda mutakhir. Stoplight mengikuti format Spesifikasi OpenAPI, dan file spesifikasi tersebut berfungsi di Apidog tanpa konversi. Struktur repo Anda kemungkinan terlihat seperti ini:

your-api-repo/
  .stoplight.json          # Konfigurasi proyek (perlu diganti)
  reference/
    petstore.yaml          # Spesifikasi OpenAPI Anda
  models/
    error.json             # Model Skema JSON bersama
  docs/
    introduction.md        # Halaman panduan Markdown
    authentication.md
  toc.json                 # Urutan daftar isi (perlu diganti)
  assets/
    images/
      architecture.png

Jika Anda menggunakan Stoplight Platform (di-host di cloud, tanpa backend Git):

Ekspor spesifikasi Anda dari UI Stoplight: buka setiap proyek API, pergi ke "Export", dan unduh OpenAPI YAML. Untuk dokumen Markdown, salin ke folder docs/ di repo Git baru. Stoplight tidak menawarkan ekspor massal untuk proyek non-Git, jadi lakukan ini per proyek API.

Setelah file Anda ada di repo Git (GitHub atau GitLab), lanjutkan ke langkah berikutnya.

Langkah 2: Pahami file konfigurasi yang Anda ganti

Dua file khusus Stoplight mengendalikan struktur proyek. Keduanya tidak memiliki padanan langsung di Apidog, tetapi memahami fungsinya memberi tahu Anda dengan tepat apa yang harus dikonfigurasi di Apidog sebagai gantinya.

Wawasan utamanya: .stoplight.json dan toc.json adalah milik Stoplight. Anda dapat membiarkannya di repo (Apidog mengabaikan file yang tidak dikenal), tetapi keduanya tidak akan menggerakkan apa pun di Apidog. Anda mengkonfigurasi pengaturan yang setara melalui UI proyek Apidog.

Langkah 3: Hubungkan repo Anda ke Mode Spec-First Apidog

Mode Spec-First Apidog adalah cara Anda menghubungkan repo GitHub atau GitLab ke proyek Apidog sehingga spesifikasi OpenAPI selalu dibaca dari Git, bukan dari database internal Apidog. Ini menjaga Git sebagai sumber otoritatif, dan itu berarti para insinyur Anda dapat terus mengirimkan PR untuk memperbarui spesifikasi persis seperti yang mereka lakukan saat ini.

Berikut adalah alur koneksi. Anda juga dapat meninjau dokumen GitHub tentang menghubungkan aplikasi pihak ketiga ke repositori jika Anda tidak yakin tentang pemberian izin OAuth.

1. Di Apidog, buat proyek baru Mode Spec-First
2. Otentikasi Apidog dengan akun GitHub atau GitLab Anda dan pilih repo.

3. Atur cabang: gunakan cabang default Anda (main atau master) untuk spesifikasi produksi, atau cabang fitur selama pengujian migrasi.

1. Simpan. Apidog membaca spesifikasi dan membangun dokumentasi interaktif, endpoint server mock, dan kerangka pengujian darinya.

Jika spesifikasi Anda menggunakan $ref untuk menarik skema dari direktori models/, Apidog menyelesaikan referensi tersebut relatif terhadap lokasi file spesifikasi. Tidak diperlukan konfigurasi tambahan selama jalur dalam file OpenAPI Anda benar. Untuk melihat lebih dalam bagaimana sinkronisasi Git ini bekerja, panduan sinkronisasi spesifikasi OpenAPI ke GitHub membahas mekanismenya secara rinci.

Langkah 4: Migrasikan dokumentasi Markdown Anda

Stoplight memungkinkan Anda mencampur halaman panduan Markdown dengan dokumen referensi API dalam satu sidebar. Apidog melakukan hal yang sama melalui editor dokumentasinya.

Setelah menghubungkan repo Anda, impor file Markdown docs/ Anda:

1. Di proyek Apidog, buka bagian Docs.
2. Gunakan Import > Markdown dan unggah file Anda, atau tempel konten halaman demi halaman.

Untuk aset gambar yang direferensikan dalam Markdown Anda (folder assets/images/ dalam tata letak Stoplight yang khas), unggah ke penyimpanan file Apidog dan perbarui referensi ![alt](path) di setiap halaman. Jika gambar Anda sudah di-host di CDN atau URL publik, Anda tidak perlu mengubah apa pun.

Langkah 5: Ganti server mock Stoplight

Stoplight Studio menyertakan server mock lokal yang membaca spesifikasi OpenAPI Anda dan mengembalikan respons contoh. Server mock Apidog melakukan hal yang sama, tetapi di-host di cloud dan dapat diakses oleh seluruh tim Anda tanpa menjalankan proses lokal.

Setelah spesifikasi Anda terhubung melalui Mode Spec-First, Apidog secara otomatis menghasilkan endpoint mock untuk setiap operasi yang didefinisikan dalam file OpenAPI Anda. Respons contoh berasal dari bidang examples dalam spesifikasi Anda, atau dari mesin mock pintar Apidog jika tidak ada contoh yang didefinisikan. Anda dapat menimpa aturan respons per endpoint di dalam Apidog tanpa menyentuh file spesifikasi.

Untuk tim yang terbiasa menjalankan stoplight mock reference/your-api.yaml secara lokal, pergeserannya adalah insinyur QA dan pengembang frontend Anda sekarang mengakses URL cloud bersama. Ini patut divalidasi dalam uji coba untuk mengkonfirmasi apakah sesuai dengan kebijakan akses jaringan Anda.

Langkah 6: Bangun ulang suite pengujian Anda

Jika Anda menggunakan pengujian kontrak Stoplight atau aturan Spectral untuk linting, hal tersebut perlu penanganan terpisah.

Aturan lint Spectral: Stoplight menggunakan Spectral untuk linting OpenAPI, yang dikonfigurasi melalui file .spectral.yaml. Apidog memiliki aturan lint bawaannya sendiri untuk kepatuhan OpenAPI, tetapi tidak menjalankan Spectral secara langsung. Jika Anda memiliki aturan Spectral kustom yang diandalkan tim Anda, terus jalankan di CI (GitHub Actions atau GitLab CI) secara independen dari Apidog. Cakupan lint Apidog dan apakah Anda dapat berbagi set aturan lint kustom di seluruh proyek patut diverifikasi dalam uji coba terhadap persyaratan aturan spesifik Anda.

Pengujian API: Stoplight Platform menyertakan pengujian API berbasis skenario. Penjalur pengujian Apidog memungkinkan Anda membangun skenario pengujian secara visual, merangkai permintaan, dan menjalankan pernyataan terhadap badan respons, header, dan kode status. Anda akan membangun ulang ini di dalam Apidog; tidak ada impor otomatis dari proyek pengujian Stoplight. Panduan alur kerja API git-native menunjukkan cara mengintegrasikan jalankan pengujian Apidog ke dalam pipeline GitHub Actions.

Contoh yang dikerjakan: jika pengujian Stoplight Anda memverifikasi bahwa POST /orders mengembalikan 201 dengan header location, berikut adalah penyiapan pengujian Apidog yang setara dalam pipeline CI menggunakan Apidog CLI:

# .github/workflows/api-tests.yml
name: API contract tests

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog tests
        run: |
          npx apidog-cli run \
            --project-id ${{ secrets.APIDOG_PROJECT_ID }} \
            --test-id ${{ secrets.APIDOG_TEST_SUITE_ID }} \
            --env production \
            --reporter junit \
            --output test-results.xml
        env:
          APIDOG_API_KEY: ${{ secrets.APIDOG_API_KEY }}

      - name: Publish test results
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: test-results.xml

Ini menggantikan jalankan pengujian Stoplight di CI dan menjaga struktur GitHub Actions Anda yang sudah ada tetap utuh.

Daftar periksa evaluasi untuk tim perusahaan

Jika Anda bermigrasi untuk tim yang lebih besar (jenis yang mengevaluasi Stoplight Platform daripada Studio), ada kemampuan spesifik yang patut diverifikasi sebelum berkomitmen. Apidog mencakup area ini, tetapi perilaku pastinya tergantung pada paket dan konfigurasi ruang kerja Anda.

Jadikan ini sebagai tugas evaluasi, bukan penghalang. Sebagian besar dapat dikonfirmasi dalam uji coba dua minggu dengan proyek perwakilan.

FAQ

Bisakah saya tetap menggunakan Spectral dengan Apidog?

Ya. Jalankan Spectral di pipeline CI Anda secara independen dari Apidog. File .spectral.yaml Anda tetap berada di repo, dan pekerjaan CI Anda (GitHub Actions, GitLab CI) melakukan linting pada file OpenAPI di setiap PR. Apidog menangani dokumentasi, mocking, dan pengujian; Spectral menangani linting. Keduanya tidak berkonflik. Lihat dokumentasi Spectral untuk opsi integrasi CI.

Apakah jalur $ref saya akan rusak saat saya menghubungkan repo ke Apidog?

Tidak jika jalur Anda benar di file spesifikasi. Apidog menyelesaikan $ref relatif terhadap lokasi file OpenAPI root. Jika spesifikasi Anda mengatakan $ref: '../models/error.json' dan folder models/ berada satu tingkat di atas reference/, Apidog mengikuti jalur relatif tersebut di repo. Uji dengan spesifikasi yang menggunakan ref eksternal terlebih dahulu.

Apakah Mode Spec-First Apidog mendukung GitLab maupun GitHub?

Ya, baik GitHub maupun GitLab didukung. Alur koneksinya sama; Anda mengautentikasi dengan akun GitLab Anda dan memilih repo serta cabang. Untuk lebih lanjut tentang opsi kontrol versi, panduan kontrol versi OpenAPI dengan Git membahas strategi cabang secara rinci.

Apa yang terjadi pada URL dokumen Stoplight saya yang sudah ada setelah migrasi?

URL dokumentasi yang di-host Stoplight (docs.stoplight.io/your-org/your-api) akan berhenti berfungsi setelah Anda membatalkan langganan Stoplight Anda. Apidog memberi dokumen Anda URL baru pada subdomain yang Anda konfigurasikan. Siapkan pengalihan di lapisan DNS atau CDN jika Anda memiliki tautan eksternal yang mengarah ke halaman dokumen Stoplight Anda.

Apakah saya perlu menghapus .stoplight.json dan toc.json dari repo?

Tidak. Apidog mengabaikan file yang tidak dikenalinya. Biarkan saja jika menghapusnya akan menyebabkan konflik penggabungan atau kebingungan. Setelah tim sepenuhnya menggunakan Apidog, Anda dapat menghapusnya dalam PR pembersihan, tetapi itu tidak wajib agar migrasi berfungsi.

Kesimpulan

Migrasi dari Stoplight ke Apidog tidak berarti memulai dari awal. Spesifikasi OpenAPI Anda tetap di Git, alur kerja cabang Anda tetap utuh, dan struktur direktori reference/, models/, dan docs/ Anda terpetakan dengan rapi ke apa yang diharapkan Apidog. Migrasi ini adalah pertukaran konfigurasi: ganti .stoplight.json dan toc.json dengan pengaturan proyek Apidog, hubungkan repo Anda melalui Mode Spec-First, dan bangun ulang skenario pengujian Anda di dalam penjalur pengujian Apidog.

Mulai migrasi Stoplight Anda dengan menghubungkan Mode Spec-First Apidog ke repo OpenAPI GitHub atau GitLab Anda yang sudah ada. Tanpa unggah ulang, tanpa penguncian vendor, riwayat Git yang sama. Unduh Apidog untuk memulai, dan gunakan proyek API perwakilan untuk uji coba Anda guna meninjau daftar periksa evaluasi di atas dengan data Anda yang sebenarnya.