วิธี Migrate จาก Redocly ไปยัง Apidog โดยไม่สูญเสียเวิร์กโฟลว์ Docs-as-Code

หากคุณใช้งาน developer portal บน Redocly คุณก็ทำงานในแบบที่ทีม API ส่วนใหญ่ต้องการอยู่แล้ว: openapi.yaml อยู่ใน Git, คู่มือเป็น Markdown, และการ push จะอัปเดตเอกสาร ความกลัวเมื่อเปลี่ยนเครื่องมือคือการสูญเสียลูปนั้นและต้องมาแก้ไขเอกสารด้วยมือในเว็บ UI

คุณไม่จำเป็นต้องทำเช่นนั้น Apidog Spec-first Mode เก็บ spec และ Markdown ของคุณไว้ใน repository เดียวกัน ซิงค์ทุกครั้งที่ push ผ่าน webhook และเผยแพร่ portal ที่มีคู่มือและ API reference ใน sidebar เดียวกัน คู่มือนี้จะพาคุณผ่านการย้าย รวมถึงส่วนหนึ่งที่ไม่สามารถย้ายโดยอัตโนมัติได้: เนื้อหาแบบยาวที่ผู้ใช้ Redocly หลายคนเก็บไว้ใน info.description และ tags[].description

หากคุณยังเปรียบเทียบเครื่องมืออยู่ เริ่มจาก Apidog vs. Redocly หรือรายการ Redocly alternatives ที่กว้างขึ้น บทความนี้ถือว่าคุณเลือก Apidog แล้วและต้องการย้ายโดยไม่ทำให้ workflow เสียหาย

สิ่งที่ถ่ายโอนได้และสิ่งที่ไม่ได้

เราทดสอบการย้ายนี้ด้วย spec ของ production จริง: OpenAPI 3.0.3, 62 operations ใน 13 tags โดยมีเนื้อหา getting-started, authentication และ integration ที่เขียนไว้ในฟิลด์ description ของ spec นี่คือสิ่งที่เกิดขึ้นเมื่อนำเข้า

API reference ย้ายมาโดยไม่ต้องแก้ไข ช่องว่างคือเนื้อหาเชิงบรรยาย

ทำไมฟิลด์ description ของคุณจึงเรนเดอร์ไม่เหมือนเดิม

Redoc ซึ่งเป็น renderer ที่อยู่เบื้องหลังเอกสารอ้างอิงของ Redocly มอง info.description เป็นมินิเอกสาร ทุกหัวข้อ Markdown ภายในจะกลายเป็นรายการใน sidebar ดังนั้นทีมจึงมักเขียนคู่มือ “Getting started” และ “Authentication” ทั้งหมดไว้ที่นั่น คำอธิบายแท็กจะเรนเดอร์เป็นข้อความแนะนำที่ด้านบนของแต่ละกลุ่มแท็ก

นั่นเป็นธรรมเนียมของ Redoc ไม่ใช่ส่วนหนึ่งของ OpenAPI Specification สเปกกำหนดเพียง description เป็นสตริง CommonMark เท่านั้น Apidog เช่นเดียวกับ portal ส่วนใหญ่ เก็บคู่มือเป็นเอกสาร Markdown แยกต่างหาก และเก็บสเปกไว้สำหรับการอ้างอิง การเผยแพร่เริ่มต้นหลังนำเข้าจะแสดงเฉพาะ API reference โดยไม่มีคู่มือที่คุณเขียนไว้ในฟิลด์ description

วิธีแก้คือการย้ายครั้งเดียว: ยกเนื้อหานั้นออกจาก YAML ไปยังไฟล์ Markdown ที่อยู่ข้าง ๆ หลังจากนั้น ทุกอย่างจะขับเคลื่อนด้วย Git ต่อไป

โครงสร้าง repository เป้าหมาย

นี่คือโครงสร้างที่เราตรวจสอบแล้ว:

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

openapi.yaml ขับเคลื่อน API reference แต่ละไฟล์ใน docs/ จะกลายเป็นหน้าใน sidebar ของ portal รูปภาพที่อ้างอิงโดยไฟล์ Markdown เหล่านั้นสามารถอยู่ใน repo เดียวกันและซิงค์ไปด้วยกัน

หากคุณใช้ sidebars.yaml ของ Redocly เพื่อจัดลำดับ navigation ให้เก็บไว้เป็นข้อมูลอ้างอิง คุณจะตั้งลำดับเดียวกันครั้งเดียวในการตั้งค่า docs site ของ Apidog

การย้ายทีละขั้นตอน

1. ตรวจสอบสิ่งที่อยู่ภายในฟิลด์ description ของคุณ

ก่อนย้ายสิ่งใด ดูว่ามีเนื้อหาอยู่ใน spec มากแค่ไหน ด้วย 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

รายการหัวข้อคือรายการไฟล์ docs/ ในอนาคตของคุณ ในการทดสอบของเรา info.description ถูกแยกออกเป็นไฟล์ Markdown สองไฟล์ และคำอธิบายแท็กกลายเป็นหน้าแนะนำต่อโฟลเดอร์บวกกับไฟล์ Markdown เพิ่มอีกหนึ่งไฟล์

2. แยก info.description เป็นไฟล์ Markdown

คัดลอกแต่ละส่วนระดับบนสุดไปยังไฟล์ของตัวเองภายใต้ docs/ เก็บหัวข้อ ตัวอย่างโค้ด และลิงก์ไว้ จากนั้นย่อ info.description ใน spec ให้เหลือเพียงสรุปหนึ่งย่อหน้า เพื่อให้เนื้อหาอยู่ในที่เดียวเท่านั้น

ระวังคุณสมบัติเฉพาะของ Redoc สองอย่างขณะคัดลอก:

• <SecurityDefinitions /> และแท็ก Redoc ที่คล้ายกันจะไม่เรนเดอร์นอก Redoc แทนที่ด้วยส่วนที่เขียนสั้น ๆ ซึ่งลิงก์ไปยัง security schemes ในการอ้างอิง
• ลิงก์เช่น #tag/Payments ชี้ไปยัง anchor ของ Redoc อัปเดตเป็น URL ของเอกสารหรือโฟลเดอร์ Apidog ที่ตรงกันหลังการเผยแพร่ครั้งแรก

3. เชื่อมต่อ repository ใน Spec-first Mode

สร้างโปรเจกต์ใน Spec-first Mode เชื่อมต่อ repository ของคุณ (GitHub, GitLab, Azure DevOps หรือ Bitbucket) ชี้ไปที่ openapi.yaml และโฟลเดอร์ docs/ และติดตั้ง webhook จากนั้นเป็นต้นไป การ push ไปยังแบรนช์ที่ติดตามจะอัปเดตโปรเจกต์

หลังการซิงค์ครั้งแรก workspace Specs จะแสดง spec และส่วนที่เหลือของ repository แท็บ APIs แสดงรายการ operations ที่แยกวิเคราะห์จาก openapi.yaml Docs เก็บหน้า Markdown ของคุณ และ All files สะท้อน repo

webhook คือสิ่งที่ทำให้สิ่งนี้เป็น workflow แบบ docs-as-code หากไม่มีคุณจะต้องทริกเกอร์การซิงค์ด้วยมือ สำหรับทบทวนว่าทำไมสิ่งนี้จึงสำคัญ ดูคู่มือของเราเกี่ยวกับ docs as code

4. เผยแพร่ docs site และตั้งค่า navigation

เผยแพร่ docs site จากโปรเจกต์และจัดเรียง sidebar ลำดับที่ผู้ใช้ Redocly ส่วนใหญ่ต้องการ และเป็นลำดับที่เราทำซ้ำได้คือ:

1. เริ่มต้นใช้งาน
2. การรับรองความถูกต้อง
3. คู่มือการรวมระบบ
4. API Reference (โฟลเดอร์ endpoint จากแท็กของคุณ)

หน้า Markdown และโฟลเดอร์ API ผสมกันได้อย่างอิสระในแผนผังเดียว ดังนั้นคุณจึงสามารถจับคู่ sidebar Redocly ปัจจุบันของคุณได้อย่างใกล้เคียง

5. เพิ่มโดเมนที่กำหนดเอง

ชี้ CNAME เช่น developers.example.com ไปที่ docs site โดเมนที่กำหนดเองมีให้ใช้ในแผนฟรี

ให้ coding agent ของคุณย้ายคำอธิบายแท็กด้วย Apidog CLI

คำอธิบายแท็กเป็นส่วนที่น่าเบื่อที่สุด สิบสามแท็กหมายถึงงานคัดลอกวางสิบสามงาน และคุณจะทำซ้ำทุกครั้งที่คำอธิบายแท็กเปลี่ยนระหว่างการเปลี่ยนผ่าน มอบหมายให้ coding agent ของคุณแทน

Apidog CLI ให้ Claude Code, Codex, Cursor หรือ agent ใน terminal ใด ๆ เข้าถึงโปรเจกต์ของคุณในรูปแบบ JSON ที่มีโครงสร้าง รวมถึงโฟลเดอร์ endpoint ตั้งค่าครั้งเดียว:

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

บรรทัดสุดท้ายติดตั้ง Apidog skill เพื่อให้ agent ของคุณรู้คำสั่งโดยไม่ต้องเดา คู่มือการติดตั้ง ครอบคลุมโทเค็นและการปรับใช้แบบส่วนตัว

จากนั้นให้ prompt หนึ่งอย่างกับ agent ของคุณ:

อ่าน openapi.yaml สำหรับทุกแท็กที่มี description ให้ค้นหาโฟลเดอร์ endpoint ที่ตรงกันในโปรเจกต์ Apidog <PROJECT_ID> และตั้งค่า description ของโฟลเดอร์นั้นเป็น description ของแท็ก ตรวจสอบ payload แต่ละอันด้วย apidog cli-schema validate folder-update ก่อนเขียน แสดงรายการโฟลเดอร์ที่คุณเปลี่ยน

นี่คือสิ่งที่ 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

สคีมา folder-update ยอมรับ name, parentId และ description และ description รองรับบนโฟลเดอร์ endpoint และ test-scenario สำหรับคู่มือที่ไม่ได้เป็นของแท็กเดียว agent สามารถใช้ apidog doc list และ apidog doc create ในลักษณะเดียวกันได้ หลังจากอ่าน apidog cli-schema get doc-create

หากต้องการแสดงคำแนะนำของโฟลเดอร์บนไซต์ที่เผยแพร่ ให้ตั้งค่า Folder Contents Displaying Setting ในการตั้งค่าโฟลเดอร์ภายใต้ Documentation Settings after Publication

ข้อควรระวังอย่างตรงไปตรงมา: การแสดงคำอธิบายแท็กเป็นหน้าแนะนำต่อหมวดหมู่ได้ผล แต่มันอาศัยเส้นทางที่เอกสารน้อยกว่า ทดสอบกับสองสามโฟลเดอร์ใน workspace ของคุณก่อนที่จะพึ่งพามันสำหรับทั้งหมด สำหรับงาน spec ที่ขับเคลื่อนด้วย agent เพิ่มเติม ดู การใช้ Apidog CLI ใน Claude Code และ การให้ agent อัปเดต API spec ของคุณ

สิ่งที่อยู่นอก Git

โปรเจกต์ Spec-first เก็บ API และ Markdown ของคุณไว้ใน Git การตั้งค่า portal บางอย่างอยู่ในอินเทอร์เฟซ Apidog และไม่ได้ถูกควบคุมเวอร์ชัน:

สิ่งเหล่านี้เป็นการตั้งค่าครั้งเดียว คุณจะแตะต้องเมื่อเพิ่มส่วนระดับบนสุดใหม่ ไม่ใช่ทุกครั้งที่เนื้อหาเปลี่ยน Redocly เก็บสิ่งเหล่านี้ไว้มากกว่าใน redocly.yaml และ sidebars.yaml ดังนั้นหากคุณตรวจสอบการเปลี่ยนแปลง navigation ใน pull request วันนี้ ให้วางแผนว่าสิ่งนั้นจะย้ายไปใน UI

แผนและราคา

การตั้งค่าที่อธิบายที่นี่เหมาะกับแผนฟรี รวมโดเมนที่กำหนดเอง แผนฟรีครอบคลุมสมาชิกทีมสูงสุด 4 คน แผนแบบชำระเงินเพิ่มสิ่งต่าง ๆ เช่น หลาย documentation site ต่อโปรเจกต์ และการควบคุมการมองเห็นแบบกำหนดเอง ตรวจสอบ ราคา Apidog สำหรับขีดจำกัดปัจจุบัน

Redocly vs. Apidog หลังการย้าย

การแลกเปลี่ยนนั้นง่าย คุณสูญเสีย navigation ที่กำหนดด้วย YAML คุณได้การทดสอบ, mocking และ CLI ที่เป็นมิตรกับ agent บน spec เดียวกันกับที่เอกสารของคุณมาจาก สำหรับการเปรียบเทียบ CLI ต่อ CLI อ่าน Apidog CLI vs Redocly CLI

คำถามที่พบบ่อย

URL ที่โฮสต์บน Redocly ของฉันจะยังใช้งานได้หรือไม่? ไม่โดยอัตโนมัติ path ของหน้าเปลี่ยน หาก portal เก่าของคุณมี URL คู่มือที่มีทราฟฟิกสูง ให้เพิ่มการเปลี่ยนเส้นทางที่ DNS หรือ proxy layer สำหรับหน้าหลักหลังจากคุณเปลี่ยนโดเมน

ฉันต้องเขียน OpenAPI spec ใหม่หรือไม่? ไม่ สเปกนำเข้าได้ตามที่เป็น คุณเพียงย้ายเนื้อหาเชิงบรรยายออกจาก info.description และ tags[].description ไปยังไฟล์ Markdown

ฉันเก็บ x-tagGroups ไว้ได้หรือไม่? ใช้โฟลเดอร์สำหรับการจัดกลุ่มแทน แต่ละแท็กจะกลายเป็นโฟลเดอร์ และคุณสามารถซ้อนโฟลเดอร์เพื่อจำลองกลุ่มแท็กของคุณได้

สิ่งนี้เปรียบเทียบกับการย้ายจาก Stoplight อย่างไร? รูปแบบคล้ายกัน: spec ใน Git, Markdown ข้าง ๆ, การซิงค์ผ่าน webhook ดู วิธี migrate จาก Stoplight ไปยัง Apidog หากคุณใช้ทั้งสองเครื่องมือ

จะเกิดอะไรขึ้นหากขั้นตอนหนึ่งทำงานแตกต่างใน workspace ของฉัน? ผลลัพธ์ของเรามาจากสภาพแวดล้อมทดสอบ ให้รันการนำเข้าซ้ำบนแบรนช์ก่อน และเปรียบเทียบ portal ที่เผยแพร่กับอันปัจจุบันของคุณก่อนเปลี่ยน DNS

ย้ายในหนึ่งบ่าย

การย้ายจาก Redocly ไป Apidog ส่วนใหญ่เป็นการย้ายเนื้อหา spec ของคุณนำเข้าได้ตามที่เป็น คู่มือของคุณย้ายออกจากฟิลด์ description ไปยังโฟลเดอร์ docs/ ครั้งเดียว webhook จะทำให้ทุกอย่างซิงค์กันหลังจากนั้น ให้ agent ของคุณจัดการงานซ้ำ ๆ อย่างคำอธิบายแท็กด้วย Apidog CLI และใช้เวลาของคุณตรวจสอบ portal ที่เผยแพร่ทีละหน้า

ดาวน์โหลด Apidog และเชื่อมต่อ repo ของคุณกับ Spec-first Mode เพื่อเริ่มการย้าย