Cara Migrasi dari Redocly ke Apidog Tanpa Kehilangan Alur Kerja Docs-as-Code

Jika Anda menjalankan portal developer di Redocly, Anda sudah bekerja dengan cara yang diinginkan sebagian besar tim API: openapi.yaml berada di Git, panduan dalam Markdown, dan push memperbarui dokumentasi. Kekhawatiran saat berganti alat adalah kehilangan alur tersebut dan berakhir mengedit dokumentasi secara manual di UI web.

Anda tidak harus begitu. Mode Spec-first Apidog menyimpan spec dan Markdown Anda di repositori yang sama, menyinkronkan setiap push melalui webhook, dan menerbitkan portal dengan panduan serta referensi API dalam satu sidebar. Panduan ini membahas migrasinya, termasuk satu bagian yang tidak ikut secara otomatis: konten panjang yang banyak pengguna Redocly simpan di dalam info.description dan tags[].description.

Jika Anda masih membandingkan alat, mulailah dengan Apidog vs. Redocly atau daftar yang lebih luas tentang alternatif Redocly. Tulisan ini mengasumsikan Anda sudah memilih Apidog dan ingin bermigrasi tanpa merusak alur kerja Anda.

Apa yang ikut dan apa yang tidak

Kami menguji migrasi ini dengan spec produksi nyata: OpenAPI 3.0.3, 62 operasi di 13 tag, dengan konten getting started, autentikasi, dan integrasi yang ditulis ke dalam field description spec. Berikut yang terjadi saat impor.

Referensi API berpindah tanpa edit. Celahnya adalah konten naratif.

Mengapa field description Anda tidak dirender dengan cara yang sama

Redoc, renderer di balik dokumentasi referensi Redocly, memperlakukan info.description sebagai dokumen mini. Setiap heading Markdown di dalamnya menjadi entri sidebar, sehingga tim sering menulis seluruh panduan “Getting started” dan “Authentication” mereka di sana. Deskripsi tag dirender sebagai teks intro di bagian atas setiap grup tag.

Itu adalah konvensi Redoc, bukan bagian dari Spesifikasi OpenAPI. Spec hanya mendefinisikan description sebagai string CommonMark. Apidog, seperti sebagian besar portal, menyimpan panduan sebagai dokumen Markdown mandiri dan menyimpan spec untuk referensi. Publikasi default setelah impor hanya menampilkan referensi API, tanpa panduan yang Anda tulis di field description.

Perbaikannya adalah pemindahan sekali saja: angkat konten itu keluar dari YAML ke file Markdown di sebelahnya. Setelah itu, semuanya tetap digerakkan oleh Git.

Tata letak repositori target

Ini struktur yang kami validasi:

your-repo/
├── openapi.yaml              # source of truth for the API reference
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── embed-integration-guide.md

openapi.yaml menggerakkan referensi API. Setiap file di docs/ menjadi halaman di sidebar portal. Gambar yang direferensikan oleh file Markdown tersebut dapat berada di repo yang sama dan disinkronkan dengannya.

Jika Anda menggunakan sidebars.yaml Redocly untuk mengurutkan navigasi, simpan sebagai referensi. Anda akan mengatur urutan yang sama sekali di pengaturan situs dokumentasi Apidog.

Migrasi langkah demi langkah

1. Audit apa yang ada di dalam field description Anda

Sebelum memindahkan apa pun, lihat berapa banyak konten yang ada di spec. Dengan yq:

# How long is the top-level description?
yq '.info.description' openapi.yaml | wc -w

# Which headings does it contain? Each one is a Redoc sidebar entry today.
yq '.info.description' openapi.yaml | grep -E '^#{1,3} '

# Which tags carry a description?
yq '.tags[] | select(.description != null) | .name' openapi.yaml

Daftar heading adalah daftar file docs/ Anda nanti. Dalam pengujian kami, info.description terbagi menjadi dua file Markdown, dan deskripsi tag menjadi halaman intro per folder plus satu file Markdown tambahan.

2. Pisahkan info.description menjadi file Markdown

Salin setiap bagian tingkat atas ke file sendiri di bawah docs/. Pertahankan heading, contoh kode, dan tautan. Lalu perkecil info.description di spec menjadi ringkasan satu paragraf, sehingga konten hanya berada di satu tempat.

Perhatikan dua fitur khusus Redoc saat Anda menyalin:

• <SecurityDefinitions /> dan tag Redoc serupa tidak dirender di luar Redoc. Ganti dengan bagian tertulis singkat yang menautkan ke skema keamanan di referensi.
• Tautan seperti #tag/Payments mengarah ke anchor Redoc. Perbarui ke URL dokumen atau folder Apidog yang cocok setelah publikasi pertama.

3. Hubungkan repositori di Mode Spec-first

Buat proyek di Mode Spec-first, hubungkan repositori Anda (GitHub, GitLab, Azure DevOps, atau Bitbucket), arahkan ke openapi.yaml dan folder docs/, lalu pasang webhook. Setelah itu, push ke branch yang dilacak akan memperbarui proyek.

Setelah sinkronisasi pertama, workspace Specs menampilkan spec Anda dan bagian lain repositori. Tab APIs mencantumkan operasi yang diurai dari openapi.yaml, Docs menyimpan halaman Markdown Anda, dan All files mencerminkan repo.

Webhook inilah yang menjaga alur kerja docs-as-code ini. Tanpanya, Anda harus memicu sinkronisasi secara manual. Untuk penyegaran mengapa ini penting, lihat panduan kami tentang docs as code.

4. Terbitkan situs dokumentasi dan atur navigasi

Terbitkan situs dokumentasi dari proyek dan atur sidebar. Urutan yang diinginkan sebagian besar pengguna Redocly, dan yang kami reproduksi, adalah:

1. Memulai
2. Autentikasi
3. Panduan integrasi
4. Referensi API (folder endpoint dari tag Anda)

Halaman Markdown dan folder API dapat dicampur dengan bebas dalam satu pohon, sehingga Anda dapat menyamai sidebar Redocly Anda saat ini dengan cukup dekat.

5. Tambahkan domain kustom Anda

Arahkan CNAME seperti developers.example.com ke situs dokumentasi. Domain kustom tersedia di paket Free.

Biarkan coding agent Anda memigrasikan deskripsi tag dengan Apidog CLI

Deskripsi tag adalah bagian yang paling membosankan. Tiga belas tag berarti tiga belas pekerjaan salin-tempel, dan Anda akan mengulanginya setiap kali deskripsi tag berubah selama transisi. Serahkan saja ke coding agent Anda.

Apidog CLI memberi Claude Code, Codex, Cursor, atau agent terminal apa pun akses JSON terstruktur ke proyek Anda, termasuk folder endpoint. Siapkan sekali:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_ACCESS_TOKEN>
npx -y skills add https://apidog.com

Baris terakhir memasang skill Apidog agar agent Anda mengetahui perintahnya tanpa menebak-nebak. Panduan instalasi mencakup token dan deployment privat.

Lalu beri agent Anda satu prompt:

Baca openapi.yaml. Untuk setiap tag dengan deskripsi, temukan folder endpoint yang cocok di proyek Apidog <PROJECT_ID> dan atur deskripsi folder tersebut ke deskripsi tag. Validasi setiap payload dengan apidog cli-schema validate folder-update sebelum menulis. Tunjukkan daftar folder yang Anda ubah.

Berikut yang dijalankan agent:

# Find the folder IDs that correspond to your tags
apidog folder list --project <PROJECT_ID> --type endpoint

# Check the payload shape instead of guessing it
apidog cli-schema get folder-update

# For each tag: write {"description": "..."} to a file, validate, then update
apidog cli-schema validate folder-update --file ./payments-folder.json
apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \
  --file ./payments-folder.json

Skema folder-update menerima name, parentId, dan description, dan description didukung pada folder endpoint dan test-scenario. Untuk panduan yang tidak termasuk dalam satu tag, agent dapat menggunakan apidog doc list dan apidog doc create dengan cara yang sama, setelah membaca apidog cli-schema get doc-create.

Untuk menampilkan intro folder di situs yang diterbitkan, atur Folder Contents Displaying Setting di pengaturan folder pada Documentation Settings after Publication.

Satu catatan jujur: menampilkan deskripsi tag sebagai halaman intro per kategori bisa berhasil, tetapi mengandalkan jalur yang kurang terdokumentasi. Uji pada dua atau tiga folder di workspace Anda sendiri sebelum Anda bergantung padanya untuk semuanya. Untuk lebih banyak pekerjaan spec yang digerakkan agent, lihat menggunakan Apidog CLI di Claude Code dan membiarkan agent memperbarui spesifikasi API Anda.

Apa yang tetap di luar Git

Proyek Spec-first menyimpan API dan Markdown Anda di Git. Beberapa pengaturan portal berada di antarmuka Apidog dan tidak dikontrol versi:

Ini adalah item yang diatur sekali. Anda menyentuhnya saat menambahkan bagian tingkat atas baru, bukan pada setiap perubahan konten. Redocly menyimpan lebih banyak dari ini di redocly.yaml dan sidebars.yaml, jadi jika Anda meninjau perubahan navigasi di pull request saat ini, rencanakan agar itu berpindah ke UI.

Paket dan harga

Pengaturan yang dijelaskan di sini cocok dengan paket Free, termasuk domain kustom. Free mencakup hingga 4 anggota tim. Paket berbayar menambahkan hal-hal seperti beberapa situs dokumentasi per proyek dan kontrol visibilitas kustom. Lihat harga Apidog untuk batasan terkini.

Redocly vs. Apidog setelah migrasi

Pertukarannya sederhana. Anda kehilangan navigasi yang didefinisikan YAML. Anda mendapatkan pengujian, mocking, dan CLI yang ramah agent pada spec yang sama dengan sumber dokumentasi Anda. Untuk perbandingan CLI demi CLI, baca Apidog CLI vs Redocly CLI.

FAQ

Apakah URL yang dihosting Redocly saya akan tetap berfungsi? Tidak secara otomatis. Path halaman berubah. Jika portal lama Anda memiliki URL panduan dengan trafik tinggi, tambahkan redirect di lapisan DNS atau proxy untuk halaman utama setelah Anda mengganti domain.

Apakah saya harus menulis ulang spec OpenAPI saya? Tidak. Spec diimpor apa adanya. Anda hanya memindahkan konten naratif dari info.description dan tags[].description ke file Markdown.

Bisakah saya mempertahankan x-tagGroups? Gunakan folder untuk pengelompokan sebagai gantinya. Setiap tag menjadi folder, dan Anda dapat menyarangkan folder untuk mereproduksi grup tag Anda.

Bagaimana ini dibandingkan dengan migrasi dari Stoplight? Bentuknya serupa: spec di Git, Markdown di sebelahnya, sinkronisasi webhook. Lihat cara migrasi dari Stoplight ke Apidog jika Anda menjalankan kedua alat.

Bagaimana jika suatu langkah berperilaku berbeda di workspace saya? Hasil kami berasal dari lingkungan pengujian. Jalankan ulang impor di branch terlebih dahulu dan bandingkan portal yang diterbitkan dengan portal Anda saat ini sebelum mengganti DNS.

Lakukan migrasi dalam satu sore

Migrasi Redocly ke Apidog sebagian besar adalah pemindahan konten. Spec Anda diimpor apa adanya. Panduan Anda dipindahkan keluar dari field description ke folder docs/ sekali saja. Webhook menjaga semuanya tetap sinkron setelah itu. Biarkan agent Anda menangani pekerjaan deskripsi tag yang repetitif dengan Apidog CLI, dan habiskan waktu Anda sendiri untuk memeriksa portal yang diterbitkan halaman demi halaman.

Unduh Apidog dan hubungkan repo Anda ke Mode Spec-first untuk memulai migrasi.