Thanawat Wongchai

Posted on Jul 14 • Originally published at apidog.com

คู่มือการโยกย้าย Stoplight สู่ Apidog: การจัดการ OpenAPI Specs ในโหมด Spec-First

การย้ายข้อมูลจาก Stoplight ไปยัง Apidog ไม่ใช่แค่การนำเข้าไฟล์ OpenAPI แต่คือการย้ายเวิร์กโฟลว์ API ที่ใช้ไฟล์เป็นหลัก ซึ่งอาจรวมถึง Spec ใน Git, เอกสาร Markdown, JSON Schema, รูปภาพ, toc.json, .stoplight.json และชุดทดสอบจากเครื่องมืออื่น

ลองใช้ Apidog วันนี้

หากนำเข้าเพียง OpenAPI ไฟล์เดียว Endpoints อาจยังอยู่ แต่บริบทของโปรเจกต์ เช่น เอกสาร การนำทาง โมเดล การทดสอบ ม็อค และ CI อาจไม่ถูกย้ายตามมา

Apidog Spec-first Mode ช่วยให้ทีมใช้ไฟล์ OpenAPI เป็น แหล่งข้อมูลที่ถูกต้องที่สุด ระหว่างการย้ายข้อมูล แล้วเชื่อมต่อไฟล์เหล่านั้นเข้ากับเอกสาร ม็อค การทดสอบ รายงาน สิทธิ์ และการทำงานร่วมกัน

สำหรับขั้นตอนการตั้งค่า ดูคู่มือช่วยเหลือ Spec-first Mode

เหตุใดการย้ายข้อมูล Stoplight จึงเป็นมากกว่าการนำเข้า OpenAPI

OpenAPI อธิบายสัญญา API แต่โปรเจกต์ Stoplight มักมีไฟล์และบริบทเพิ่มเติม เช่น

ไฟล์ OpenAPI หรือ Swagger ใน reference หรือไดเรกทอรีที่กำหนดเอง
เอกสาร Markdown ใน docs
โมเดล JSON Schema ใน models
รูปภาพภายในเครื่องที่ Markdown อ้างอิง
.stoplight.json สำหรับการกำหนดค่าเส้นทางที่รองรับ
toc.json สำหรับโครงสร้างและลำดับเอกสารที่รองรับ
Stoplight ID เช่น x-stoplight-id หรือ x-stoplight.id

หากย้ายเพียง Spec เดียว คุณอาจสูญเสียการเชื่อมโยงระหว่างเอกสาร โมเดล รูปภาพ และเวิร์กโฟลว์ที่อยู่ใน Postman, Bruno หรือ CI

ดังนั้นให้เริ่มจากการตรวจสอบ Repository ทั้งหมด ไม่ใช่เลือกนำเข้า Spec เพียงไฟล์เดียว

โมเดลการย้ายข้อมูล: โอนย้าย, ตรวจสอบ, สร้างใหม่, เชื่อมต่อ

ก่อนเริ่ม ให้กำหนดก่อนว่าอะไรคือแหล่งข้อมูลที่ถูกต้องที่สุด (source of truth)

หาก OpenAPI ใน Git คือสัญญาหลัก ให้เริ่มจากไฟล์เหล่านั้น
หาก Postman หรือ Bruno เป็นสิ่งที่กำหนดพฤติกรรม API จริง ให้แก้ไขความไม่ตรงกันก่อนย้าย

หมวดหมู่	สิ่งที่ควรรวม	แนวทาง
โอนย้าย	OpenAPI, Markdown, รูปภาพที่อ้างอิง, JSON Schema ที่รองรับ, `.stoplight.json`, `toc.json`	นำบริบทแบบไฟล์เข้าสู่ Spec-first Mode
ตรวจสอบ	ลิงก์, แองเคอร์, รูปภาพ, `$ref`, Schema, TOC, Stoplight ID และความต่างของการแสดงผล	ตรวจสอบผลลัพธ์ก่อนใช้งานจริง
สร้างใหม่	คำขอจาก Postman/Bruno, environment, tests, mocks, CI และกฎเผยแพร่	สร้างเวิร์กโฟลว์ใหม่รอบ OpenAPI
เชื่อมต่อ	เอกสาร, ม็อค, tests, CI reports, สิทธิ์ และการทำงานร่วมกัน	ใช้ Apidog เชื่อมสัญญา API กับ lifecycle ทั้งหมด

การย้ายข้อมูลมีสองชั้น:

ชั้นไฟล์ — OpenAPI, Markdown, JSON Schema, รูปภาพ และโครงสร้างโปรเจกต์
ชั้นเวิร์กโฟลว์ — การรีวิว API, การเผยแพร่เอกสาร, การทดสอบ, ม็อค, CI, รายงาน และการทำงานร่วมกัน

Spec-first Mode เหมาะกับชั้นไฟล์ ขณะที่ Apidog ช่วยเชื่อมต่อชั้นเวิร์กโฟลว์รอบสัญญา API เดียวกัน

Apidog Spec-first Mode เหมาะกับโปรเจกต์ Stoplight อย่างไร

Spec-first Mode ออกแบบมาสำหรับเวิร์กโฟลว์แบบไฟล์เป็นหลัก

Git-connected project: Repository และ Branch ใน Git ยังคงเป็นแหล่งข้อมูลที่ถูกต้องที่สุด
File-backed project: เริ่มแก้ไขไฟล์ Spec ใน Apidog ก่อน แล้วค่อยเชื่อมต่อ Git ภายหลัง
Specs workspace: จัดการไฟล์ต้นฉบับ ดูโครงสร้าง API ที่แยกวิเคราะห์ และแก้ไขไฟล์ในพื้นที่เดียว

พื้นที่ทำงาน Specs ช่วยให้ทีมจัดการไฟล์ต้นฉบับ โครงสร้าง API ที่ถูกแยกวิเคราะห์ และเวิร์กโฟลว์การแก้ไขได้ในที่เดียว

สินทรัพย์ Stoplight	สิ่งที่เกิดขึ้นใน Apidog	สิ่งที่ต้องตรวจสอบ
OpenAPI / Swagger	นำเข้าและซิงค์เป็นโมดูล API, Endpoints, Schemas และตัวอย่าง	`$ref`, คำเตือนการแปลง, ชื่อโมดูล และการจัดกลุ่ม Endpoint
`.stoplight.json`	ใช้ Root ของ OpenAPI, Markdown, JSON Schema, include/exclude patterns และ `tocPath` ที่รองรับ	อย่าคาดหวังว่าการตั้งค่า Stoplight ทุกฟิลด์จะถูกใช้เหมือนเดิม
`toc.json`	ช่วยสร้างโฟลเดอร์ DOCS, จัดเรียง Markdown, ลิงก์ OAS/โมดูล และนำเข้าโมเดลที่อ้างอิง	ตรวจสอบ sidebar สุดท้ายใน Apidog
Markdown	นำเข้าสู่เวิร์กโฟลว์เอกสารของโปรเจกต์	ลิงก์ภายใน, แองเคอร์, รูปแบบ และไฟล์ที่หายไป
รูปภาพภายในเครื่อง	นำเข้าได้เมื่อถูกอ้างอิงโดย Markdown และอยู่ในขอบเขตที่รองรับ	รูปภาพภายนอก, data URI, ลิงก์เสีย และรูปภาพที่ไม่ถูกอ้างอิง
JSON Schema	นำเข้าเป็นโมเดลได้เมื่อถูกอ้างอิงโดยโครงสร้างที่รองรับ เช่น `toc.json`	รูปแบบ Schema, การตั้งชื่อ, โฟลเดอร์ และ references
Stoplight ID	Root-level ID อาจช่วยจับคู่โมดูลระหว่างการซิงค์	อย่าพึ่งพา ID สำหรับทุก resource type

หมายเหตุความเข้ากันได้สำหรับไฟล์โปรเจกต์ Stoplight

.stoplight.json เป็นการกำหนดค่าเส้นทางสำหรับการซิงค์ที่รองรับ ไม่ใช่การย้ายการตั้งค่า Stoplight ทั้งหมด
toc.json ช่วยสร้างโครงสร้าง DOCS ที่รองรับได้ แต่ไม่รับประกันการจัดเรียงข้ามประเภทหรือ sidebar แบบเดิมทุกจุด
รูปภาพจะถูกย้ายเป็นหลักเมื่อ Markdown อ้างอิงถึงรูปภาพนั้น
JSON Schema จะคาดเดาผลลัพธ์ได้มากขึ้นเมื่อถูกอ้างอิงโดยตรงจาก toc.json หรือโครงสร้างที่รองรับ

เป้าหมายไม่ใช่การสร้าง Stoplight เดิมขึ้นใหม่แบบพิกเซลต่อพิกเซล แต่คือการรักษาโครงสร้างแบบไฟล์ และเชื่อมต่อเข้ากับ lifecycle ของ API ที่กว้างขึ้น

จากการนำเข้าไฟล์สู่เวิร์กโฟลว์ API ที่เชื่อมต่อกัน

การนำเข้า OpenAPI แบบครั้งเดียวอาจทำให้ Git, เอกสาร และ API workspace ค่อย ๆ แยกออกจากกัน

Spec-first Mode ทำให้ไฟล์ยังคงเป็นรากฐานของงาน:

ในโปรเจกต์ที่เชื่อมต่อ Git ทีมสามารถแก้ไขไฟล์ใน Specs workspace แล้ว commit และ push กลับไปยัง Repository ได้ สำหรับโปรเจกต์แบบ file-backed ทีมสามารถแก้ไขและบันทึกไฟล์ใน Apidog ก่อนเชื่อมต่อ Git

ความรับผิดชอบ	แหล่งที่มาที่แนะนำ
สัญญา API	OpenAPI / Swagger
โครงสร้างไฟล์โปรเจกต์	Repository หรือโปรเจกต์แบบ file-backed
การตั้งค่าเส้นทางที่รองรับ	`.stoplight.json`
โครงสร้างเอกสารที่รองรับ	`toc.json` และ Markdown
การทำงานร่วมกันรายวัน	Apidog project workspace
ม็อค, การทดสอบ, รายงาน และสิทธิ์	เวิร์กโฟลว์ของ Apidog

ความต่างสำคัญคือ:

การนำเข้าไฟล์: ย้ายสัญญา API เพียงครั้งเดียว
การเชื่อมต่อ Spec-first project: สร้างพื้นที่ทำงานและเวิร์กโฟลว์รอบสัญญา API นั้น

เส้นทางการย้ายข้อมูล: Git-connected vs File-backed

ทีม Stoplight ไม่ได้เริ่มจากจุดเดียวกันทั้งหมด

เส้นทาง	เหมาะสำหรับ	เวิร์กโฟลว์ทั่วไป
Git-connected Spec-first project	ทีมที่เก็บ OpenAPI ใน Git อยู่แล้ว	เชื่อม Repository, ซิงค์ Branch, แก้ไข, commit และ push
File-backed Spec-first project	ทีมที่ต้องการเริ่มจากการทำงานกับไฟล์ก่อนเชื่อม Git	แก้ไขและบันทึก Spec ใน Apidog ก่อน

สำหรับทีมส่วนใหญ่ที่ใช้ Stoplight และ Git อยู่แล้ว Git-connected project เป็นแนวทางระยะยาวที่ชัดเจนกว่า เพราะ Repository ยังคงเป็นแหล่งข้อมูลที่ถูกต้องที่สุด

เลือก file-backed project เมื่อคุณต้องการประเมินประสบการณ์การแก้ไขไฟล์ ทำความสะอาดโครงสร้างโปรเจกต์ หรือเตรียมการย้ายก่อนบังคับใช้เวิร์กโฟลว์ Git

สิ่งที่ควรตรวจสอบหลังการย้ายข้อมูล

ใช้ checklist นี้หลังสร้าง Spec-first project

พื้นที่	สิ่งที่ต้องตรวจสอบ
OpenAPI modules	Spec ที่ต้องการถูกนำเข้าครบ, ชื่อโมดูลถูกต้อง และ Endpoints ถูกจัดกลุ่มตามต้องการ
External references	`$ref` ถูกแก้ไขได้ถูกต้องและไม่มีปัญหาการแปลง
Lint / validation	รันการตรวจสอบใน Apidog Specs
`.stoplight.json`	ตรวจสอบ Root paths, include patterns, exclude patterns และ `tocPath` ที่รองรับ
`toc.json`	ตรวจสอบกลุ่ม, ตัวแบ่ง, ชื่อ, ลำดับ Markdown, ลิงก์โมดูล และ sidebar สุดท้าย
Markdown	ตรวจสอบ formatting, headings, relative links, anchors และลิงก์ API
รูปภาพ	ตรวจสอบรูปภาพภายในเครื่อง, รูปภาพภายนอก, data URI และ broken references
Models	ยืนยันว่า JSON Schema ที่อ้างอิงกลายเป็นโมเดลที่ถูกต้อง
Stoplight ID	ตรวจสอบการจับคู่โมดูลในการซิงค์ซ้ำ
Tests และ mocks	สร้างใหม่หรือเชื่อมต่อเวิร์กโฟลว์จาก Postman, Bruno หรือ CI
สิทธิ์และการเผยแพร่	กำหนด access, document visibility, review rules และผู้รับผิดชอบเผยแพร่ใหม่

Apidog สามารถใช้ไฟล์ Spectral ระดับ root ต่อไปนี้สำหรับการตรวจสอบใน Editor:

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

และสามารถใช้ .stoplight/styleguide.json เป็นทางเลือกได้

ให้ใช้ผลลัพธ์ lint เป็นสัญญาณสำหรับตรวจสอบสัญญา API ไม่ใช่หลักฐานว่าพฤติกรรมเฉพาะของ Stoplight ถูกย้ายครบทั้งหมด

แล้วสินทรัพย์ Postman และ Bruno ล่ะ?

Postman collections และ Bruno .bru files มักเก็บข้อมูลที่ต่างจาก OpenAPI เช่น

เวิร์กโฟลว์คำขอ
ตัวอย่าง request
environment
test scripts
secrets
งาน CI

ก่อนย้าย ให้ตอบคำถามต่อไปนี้

คำถาม	เหตุผล
OpenAPI หรือ collection คือแหล่งข้อมูลที่ถูกต้องที่สุด?	การย้ายแบบ Spec-first ต้องเริ่มจากสัญญาที่เชื่อถือได้
Request examples ใดที่ยังสำคัญ?	สร้างตัวอย่างสำคัญใหม่ใน API workspace
Tests ใดต้องทำงานต่อ?	ย้ายหรือเชื่อมต่อ tests เข้ากับเวิร์กโฟลว์ใหม่
Environment และ secrets ใดถูกใช้ร่วมกัน?	ต้องวางแผนแยกจากการย้าย Spec
CI jobs ใดขึ้นกับเครื่องมือเดิม?	เชื่อม validation, tests และ reports อย่างตั้งใจ

สำหรับ Bruno จุดสำคัญคือทีมมี Git-native workflow อยู่แล้ว Spec-first Mode ช่วยรักษา OpenAPI ให้เป็นแบบไฟล์ได้ แต่ Bruno assets อาจต้องย้ายหรือสร้างใหม่แยกตามรูปแบบที่ทีมใช้งาน

แผนการย้ายข้อมูลที่แนะนำ

ใช้การย้ายแบบแบ่งขั้นตอน แทนการย้ายทุกเวิร์กโฟลว์พร้อมกัน

แผนการย้ายข้อมูลแบบแบ่งขั้นตอน: ย้ายสัญญา OpenAPI ก่อน จากนั้นจึงเชื่อมต่อเวิร์กโฟลว์โดยรอบ

1. ตรวจสอบ Repository สไตล์ Stoplight

ระบุไฟล์ต่อไปนี้:

OpenAPI / Swagger
.stoplight.json
toc.json
Markdown docs
JSON Schema models
รูปภาพภายในเครื่อง
Postman / Bruno collections
CI และ test assets

2. ตัดสินใจแหล่งข้อมูลที่ถูกต้องที่สุด

ยืนยันว่า OpenAPI ใน Git คือสัญญาหลักหรือไม่

หาก collection หรือเครื่องมืออื่นกำหนด API behavior จริง ให้แก้ไขความต่างนั้นก่อนเริ่มย้าย

3. สร้างโปรเจกต์ Spec-first

เลือก Git-connected หาก Git คือ source of truth
เลือก File-backed หากต้องการทดลองและตรวจสอบไฟล์ก่อน

4. ตรวจสอบสิ่งที่โอนย้ายมา

ตรวจสอบโมดูล เอกสาร โมเดล รูปภาพ ลิงก์ toc.json .stoplight.json และผล validation

แก้ไขที่ไฟล์ต้นทางเมื่อทำได้ แทนการแก้ผลลัพธ์เฉพาะหน้าใน workspace

5. สร้างสินทรัพย์ระดับเวิร์กโฟลว์ใหม่

เชื่อมต่อหรือสร้างใหม่สำหรับ:

Mocks
Tests
Request examples
CI jobs
Reports
Team permissions
Publishing responsibilities

6. ทำการเปลี่ยนแปลงจริงครั้งแรก

ทำการเปลี่ยนแปลง OpenAPI เล็กน้อย แล้วตรวจสอบลำดับงานทั้งหมด:

แก้ไข Spec
รัน validation
ซิงค์หรือ commit การเปลี่ยนแปลง
อัปเดตเอกสารหากจำเป็น
ตรวจสอบ mocks, tests และ reports

เส้นทางนี้เหมาะที่สุดเมื่อใด

แนวทางนี้เหมาะเมื่อ:

ทีมจัดการ OpenAPI หรือ Swagger เป็นไฟล์
โปรเจกต์ Stoplight มี Markdown, models, รูปภาพ, .stoplight.json หรือ toc.json
ทีมใช้ Git branches หรือ pull requests สำหรับ API review
ต้องการเชื่อมเอกสาร ม็อค การทดสอบ รายงาน และการทำงานร่วมกันเข้ากับสัญญา API
ต้องการลดความคลาดเคลื่อนระหว่างไฟล์ API กับ workspace ที่ Frontend, QA, Product หรือ Partner ใช้

อาจต้องวางแผนเพิ่มเติมเมื่อ:

Postman หรือ Bruno collection คือ source of truth แทน OpenAPI
โปรเจกต์พึ่งพาพฤติกรรมการเผยแพร่ที่ปรับแต่งเองมาก
เอกสารมี external links, anchors, generated pages หรือสินทรัพย์ที่ไม่ถูกอ้างอิงจำนวนมาก
JSON Schema มีโครงสร้างที่ต้องตรวจสอบด้วยตนเอง
ต้องการสร้าง navigation หรือการแสดงผลของ Stoplight เดิมแบบพิกเซลต่อพิกเซล

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

Apidog Spec-first Mode เป็นทางเลือกของ Stoplight หรือไม่?

สามารถใช้เป็นทางเลือกสำหรับทีมที่ต้องการเก็บ OpenAPI เป็นไฟล์ พร้อมเพิ่มการทำงานร่วมกัน การทดสอบ ม็อค เอกสาร รายงาน และสิทธิ์รอบไฟล์เหล่านั้น

ฉันสามารถเก็บ OpenAPI Spec ไว้ใน Git ได้หรือไม่?

ได้ ใน Git-connected Spec-first project ทีมสามารถซิงค์ Branch แก้ไขไฟล์ และ commit การเปลี่ยนแปลงกลับไปยัง Repository ได้

ฉันจำเป็นต้องมี Git เพื่อเริ่มต้นหรือไม่?

ไม่จำเป็น คุณสามารถเริ่มด้วย file-backed Spec-first project แล้วเชื่อมต่อ Git ภายหลังได้

`.stoplight.json` และ `toc.json` จะถูกเก็บรักษาไว้ทั้งหมดหรือไม่?

ไม่ Apidog ใช้ส่วนที่รองรับของไฟล์เหล่านี้เป็นอินพุตการย้ายข้อมูล

.stoplight.json ใช้สำหรับค้นหาเส้นทางและการซิงค์เป็นหลัก ส่วน toc.json ช่วยจัดระเบียบเอกสาร ลิงก์โมดูล และโมเดลที่อ้างอิงได้ในขอบเขตที่รองรับ

เกิดอะไรขึ้นกับเอกสาร Markdown?

Markdown สามารถนำเข้าสู่ Spec-first project ได้ โดยเฉพาะเอกสารที่ระบุใน toc.json อย่างไรก็ตาม ควรตรวจสอบลิงก์ภายใน แองเคอร์ รูปภาพ และการแสดงผลอีกครั้ง

เกิดอะไรขึ้นกับ JSON Schema models?

JSON Schema สามารถนำเข้าได้เมื่อถูกอ้างอิงอย่างชัดเจนโดยโครงสร้างที่รองรับ เช่น toc.json

อย่าคาดหวังว่า JSON ทุกไฟล์ในไดเรกทอรี models จะถูกเปลี่ยนเป็นโมเดลโดยอัตโนมัติ

เกิดอะไรขึ้นกับรูปภาพ?

รูปภาพภายในเครื่องที่ Markdown อ้างอิงสามารถนำเข้าได้ในขอบเขตที่รองรับ ตรวจสอบรูปภาพภายนอก, data URI, broken links และรูปภาพที่ไม่ได้ถูกใช้งานแยกต่างหาก

ฉันควรรัน lint หลังการย้ายข้อมูลหรือไม่?

ควรทำ รันการตรวจสอบ Spec บน OpenAPI ที่นำเข้าแล้ว โดยใช้ไฟล์ Spectral ที่รองรับหรือ .stoplight/styleguide.json เป็นทางเลือก

ผล lint ช่วยค้นหาปัญหาสัญญาและรูปแบบ แต่ไม่ได้ยืนยันว่าพฤติกรรม Stoplight ทุกอย่างถูกเก็บรักษาไว้

ผู้ใช้ Bruno หรือ Postman ควรทำอย่างไร?

เริ่มจากระบุว่า OpenAPI หรือ collection คือ source of truth

Spec-first migration ครอบคลุม OpenAPI และไฟล์โปรเจกต์ที่เกี่ยวข้อง ส่วน request workflows, environments และ tests จาก collection อาจต้องย้ายหรือสร้างใหม่แยกต่างหาก

Apidog รองรับม็อค การทดสอบ CI/CD รายงาน และการทำงานร่วมกันหรือไม่?

รองรับ Spec-first Mode เชื่อม OpenAPI แบบไฟล์เข้ากับ Apidog และแพลตฟอร์มที่กว้างขึ้นสำหรับเอกสาร ม็อค test scenarios, CI/CD ผ่าน Apidog CLI, รายงาน สิทธิ์ และการทำงานร่วมกันของทีม

บทสรุป

การย้ายข้อมูล Stoplight ไม่ควรหมายถึงการทิ้งเวิร์กโฟลว์ API แบบไฟล์เป็นหลัก

ให้ Repository และ OpenAPI ยังคงเป็นแหล่งข้อมูลที่ถูกต้องที่สุด จากนั้นย้ายและตรวจสอบ Markdown, รูปภาพที่อ้างอิง, JSON Schema ที่อ้างอิงผ่าน TOC และไฟล์โครงสร้างโปรเจกต์ที่รองรับ

Apidog Spec-first Mode ให้แนวทางที่ใช้งานได้จริง:

โอนย้ายส่วนที่เป็นไฟล์ของโปรเจกต์
ตรวจสอบส่วนที่ขึ้นกับ Stoplight อย่างละเอียด
สร้างและเชื่อมต่อเวิร์กโฟลว์ใหม่รอบ API workspace

หากกำลังประเมินการย้ายข้อมูล ให้เริ่มจากการตรวจสอบโครงสร้าง Repository และกำหนดว่าไฟล์ใดเป็นตัวกำหนดสัญญา API จากนั้นใช้ Spec-first Mode เพื่อเชื่อมต่อไฟล์เหล่านั้นกับเอกสาร ม็อค การทดสอบ รายงาน สิทธิ์ และการทำงานร่วมกันใน Apidog

สำหรับการวางแผนการย้ายข้อมูลระดับองค์กร ดู Apidog Enterprise

DEV Community