การย้ายข้อมูลจาก Stoplight ไปยัง Apidog ไม่ใช่แค่การนำเข้าไฟล์ OpenAPI เท่านั้น แต่เป็นการเปลี่ยนผ่านเวิร์กโฟลว์ API ที่ใช้ไฟล์เป็นหลัก
สำหรับหลายทีม โปรเจกต์ Stoplight มีมากกว่าแค่ Endpoints: รายละเอียด OpenAPI ใน Git, เอกสาร Markdown, โมเดล JSON Schema, รูปภาพภายในเครื่อง, อินพุตการนำทาง toc.json ที่รองรับ และการตั้งค่าเส้นทาง .stoplight.json ที่รองรับ
ทีมอาจมีตัวอย่างคำขอใน Postman และสคริปต์การทดสอบใน CI หากการย้ายข้อมูล Stoplight ไปยัง Apidog นำเข้าเพียงไฟล์ OpenAPI เดียว รายการ Endpoints อาจยังคงอยู่ แต่เวิร์กโฟลว์จะไม่
Apidog Spec-first Mode ช่วยให้ทีมเก็บไฟล์ OpenAPI เป็น แหล่งข้อมูลที่ถูกต้องที่สุด ระหว่างการย้ายข้อมูล Stoplight ในขณะที่เชื่อมโยงไฟล์เหล่านั้นเข้ากับพื้นที่ทำงาน API ที่กว้างขึ้นสำหรับเอกสาร, ม็อค, การทดสอบ, รายงาน, สิทธิ์ และการทำงานร่วมกัน
คู่มือนี้อธิบายวิธีการวางแผนการย้ายข้อมูล: สิ่งใดที่สามารถโอนย้ายได้, สิ่งใดที่ควรตรวจสอบ, สิ่งใดที่ต้องสร้างใหม่ และสิ่งใดที่ควรเชื่อมต่อรอบสัญญา OpenAPI
สำหรับขั้นตอนการตั้งค่าการทำงาน โปรดดู คู่มือช่วยเหลือ Spec-first Mode
เหตุใดการย้ายข้อมูล Stoplight จึงเป็นมากกว่าการนำเข้า OpenAPI
ไฟล์ OpenAPI อธิบายสัญญา API โปรเจกต์สไตล์ Stoplight มักจะประกอบด้วยบริบทเพิ่มเติมรอบสัญญาดังกล่าว
สินทรัพย์โปรเจกต์ทั่วไปประกอบด้วย:
- ไฟล์ OpenAPI หรือ Swagger ซึ่งมักจะเก็บไว้ใต้
referenceหรือไดเรกทอรีที่กำหนดค่าอื่น ๆ; - เอกสาร Markdown ซึ่งมักจะเก็บไว้ใต้
docs; - ไฟล์โมเดล JSON Schema ซึ่งมักจะเก็บไว้ใต้
models; - รูปภาพภายในเครื่องที่อ้างอิงโดยเอกสาร;
.stoplight.jsonสำหรับการกำหนดค่าเส้นทางที่รองรับ;toc.jsonสำหรับอินพุตการนำทางเอกสาร, การจัดกลุ่ม และการจัดลำดับที่รองรับ;- ตัวระบุ Stoplight เช่น
x-stoplight-idหรือx-stoplight.id.
หากการย้ายข้อมูลนำเข้าเพียงไฟล์ OpenAPI เดียว Endpoints อาจถูกย้ายมา แต่โมเดลโปรเจกต์อาจยังคงหายไป เอกสารอาจต้องสร้างใหม่ การนำทางอาจไม่ตรงกับโปรเจกต์เดิม โมเดลอาจถูกตัดการเชื่อมต่อจากเอกสาร การทดสอบ, ม็อค และตัวอย่างคำขออาจยังคงอยู่ในเครื่องมือแยกต่างหาก
แผนการย้ายข้อมูลที่ดีกว่าเริ่มต้นจาก Repository หรือโครงสร้างไฟล์ ไม่ใช่จากไฟล์ Spec เพียงไฟล์เดียว
โมเดลการย้ายข้อมูล: โอนย้าย, ตรวจสอบ, สร้างใหม่, เชื่อมต่อ
ก่อนเริ่มต้น ให้ระบุแหล่งข้อมูลที่ถูกต้องที่สุด หากไฟล์ OpenAPI ใน Git กำหนดสัญญา API การย้ายข้อมูลแบบ Spec-first สามารถเริ่มต้นจากไฟล์เหล่านั้นได้ หาก Postman หรือคอลเลกชัน Bruno เป็นตัวขับเคลื่อนเวิร์กโฟลว์คำขอจริง ให้แก้ไขความไม่ตรงกันนั้นก่อน
แผนการย้ายข้อมูลที่แข็งแกร่งที่สุดไม่ใช่ "รักษาทุกอย่าง" โปรเจกต์ Stoplight อาจมีพฤติกรรมเฉพาะผลิตภัณฑ์ที่ไม่สามารถจับคู่แบบหนึ่งต่อหนึ่งกับพื้นที่ทำงานอื่นได้
ให้ใช้โมเดลสี่ส่วนแทน:
| หมวดหมู่ | สิ่งที่จะรวมไว้ | แนวทางการย้ายข้อมูล |
|---|---|---|
| โอนย้าย | ไฟล์ OpenAPI, การตั้งค่าเส้นทาง .stoplight.json ที่รองรับ, อินพุตการนำทาง toc.json ที่รองรับ, เอกสาร Markdown, รูปภาพภายในเครื่องที่อ้างอิง, และโมเดล JSON Schema ที่รองรับ | นำบริบทโปรเจกต์ที่ใช้ไฟล์เป็นหลักเข้ามาใน Spec-first Mode |
| ตรวจสอบ | ลิงก์ Markdown, แองเคอร์, รูปภาพ, การจัดกลุ่ม TOC, การตั้งชื่อ Schema, $ref ภายนอก, Stoplight ID, หน้าที่สร้างขึ้น และความแตกต่างในการแสดงผล | ตรวจสอบพื้นที่ทำงานที่ย้ายข้อมูลแล้ว ก่อนที่จะถือว่าพร้อมใช้งานจริง |
| สร้างใหม่ | เวิร์กโฟลว์คำขอ Postman หรือ Bruno, สภาพแวดล้อม, การทดสอบด้วยตนเอง, ม็อค, งาน CI และกฎการเผยแพร่ หากสิ่งเหล่านี้อยู่นอกโปรเจกต์ Spec | สร้างสิ่งเหล่านี้ใหม่รอบแหล่งข้อมูลที่ถูกต้องที่สุดของ OpenAPI |
| เชื่อมต่อ | เอกสาร API, API ม็อค, การทดสอบ, รายงาน CI, สิทธิ์, การทำงานร่วมกันเป็นทีม และเวิร์กโฟลว์ที่มุ่งเน้นพันธมิตร | ใช้ Apidog เพื่อให้สัญญา API มีประโยชน์ตลอดวงจรชีวิตของ API |
ความแตกต่างนี้มีความสำคัญเนื่องจากการย้ายข้อมูล Stoplight มีสองชั้น
ชั้นแรกคือชั้นไฟล์: รายละเอียด OpenAPI, เอกสาร Markdown, ไฟล์โมเดล, รูปภาพ และไฟล์โครงสร้างโปรเจกต์ นี่คือจุดที่ Spec-first Mode มีประโยชน์มากที่สุด
ชั้นที่สองคือชั้นเวิร์กโฟลว์: ทีมของคุณทบทวนการเปลี่ยนแปลง API อย่างไร, เผยแพร่เอกสาร, รันการทดสอบ, จัดการม็อค, แชร์รายงาน และทำงานร่วมกันระหว่างทีมแบ็กเอนด์, ฟรอนต์เอนด์, QA, ผลิตภัณฑ์ และพันธมิตร ชั้นนี้ไม่ควรถือเป็นผลพลอยได้จากการนำเข้า เป็นจุดที่ Apidog สามารถเชื่อมโยงสัญญา API เข้ากับส่วนที่เหลือของวงจรชีวิต API
Apidog Spec-first Mode เหมาะสมกับโปรเจกต์ Stoplight ได้อย่างไร
Apidog Spec-first Mode ถูกสร้างขึ้นมาสำหรับเวิร์กโฟลว์ที่ใช้ไฟล์เป็นหลัก ซึ่งเป็นสิ่งเดียวกับที่โปรเจกต์ Stoplight ของคุณใช้อยู่แล้ว
โปรเจกต์ที่เชื่อมต่อกับ Git จะเก็บ Repository ของคุณไว้เป็นศูนย์กลาง Branch ของคุณยังคงเป็นแหล่งข้อมูลที่ถูกต้องที่สุด และ Apidog จะซิงค์กับมัน
โปรเจกต์ที่ใช้ไฟล์เป็นหลักช่วยให้คุณทำงานกับไฟล์ Spec ได้โดยตรงใน Apidog ก่อน คุณสามารถเชื่อมต่อ Git ได้ในภายหลังเมื่อคุณพร้อม
พื้นที่ทำงาน Specs ให้คุณจัดการไฟล์ต้นฉบับ, ดูโครงสร้าง API ที่ถูกแยกวิเคราะห์ และจัดการเวิร์กโฟลว์การแก้ไขทั้งหมดได้ในที่เดียว
นี่คือวิธีการทำงานของสินทรัพย์ Stoplight แต่ละประเภทใน Apidog:
| สินทรัพย์ Stoplight | สิ่งที่เกิดขึ้นใน Apidog | หมายเหตุการตรวจสอบ |
|---|---|---|
| ไฟล์ OpenAPI / Swagger | สามารถนำเข้าและซิงค์เป็นโมดูล API, Endpoints, Schemas และตัวอย่าง | ตรวจสอบการอ้างอิงที่รวมอยู่, คำเตือนการแปลง, การตั้งชื่อโมดูล และการจัดกลุ่ม Endpoints |
.stoplight.json | ฟิลด์ที่รองรับสามารถช่วย Apidog ค้นหา Root ของ OpenAPI, Markdown และ JSON Schema, ใช้รูปแบบการรวม OpenAPI, ใช้รูปแบบการยกเว้นทั่วโลก และแก้ไข tocPath | ถือเป็นการค้นหาเส้นทางสำหรับการซิงค์ ไม่ใช่การกำหนดค่าโปรเจกต์ Stoplight ทั้งหมด อย่าสันนิษฐานว่าการตั้งค่า formats ของ Stoplight หรือพฤติกรรมโปรเจกต์ทั้งหมดถูกนำไปใช้ในลักษณะเดียวกัน |
toc.json | สามารถช่วย Apidog สร้างโฟลเดอร์ DOCS จากกลุ่มและตัวแบ่งที่รองรับ, กรองและจัดเรียงเอกสาร Markdown ที่ระบุใน TOC, ใช้ชื่อ TOC, เชื่อมโยงโฟลเดอร์ DOCS กับโมดูล OAS ที่นำเข้าหรือรายการ Spec ที่เลือก และนำเข้าโมเดล JSON Schema ที่อ้างอิงใน TOC ที่รองรับ | ตรวจสอบ sidebar ของ Apidog สุดท้ายหลังการนำเข้า โครงสร้างสุดท้ายจะถูกแสดงผลผ่านโมเดล DOCS/OAS/MODELS ของ Apidog ดังนั้นการนำทาง Stoplight ที่แน่นอนหรือการจัดเรียงข้ามประเภทที่ไม่จำเพาะเจาะจงอาจไม่ได้รับการเก็บรักษาไว้ |
| เอกสาร Markdown | เอกสาร Markdown สามารถนำเข้าสู่เวิร์กโฟลว์ของโปรเจกต์ได้ เอกสารที่ระบุใน TOC สามารถรักษาสิ่งก่อสร้างได้มากขึ้นในที่ที่รองรับ | ตรวจสอบลิงก์ภายใน, แองเคอร์, การจัดรูปแบบ, ไฟล์ที่ขาดหายไป และความแตกต่างในการแสดงผล |
| รูปภาพภายในเครื่อง | รูปภาพภายในเครื่องที่อ้างอิงโดย Markdown สามารถนำเข้าได้ในที่ที่รองรับ | ตรวจสอบการอ้างอิงที่เสียหาย, รูปภาพภายนอก, data URI และรูปภาพที่ไม่ได้อ้างอิงโดยเอกสาร อย่าถือว่าการตั้งค่า root ของรูปภาพเป็นการรับประกันการนำเข้าไลบรารีสินทรัพย์ |
| โมเดล JSON Schema | ไฟล์ JSON Schema ที่อ้างอิงอย่างชัดเจนโดยโครงสร้างโปรเจกต์ที่รองรับ เช่น toc.json สามารถนำเข้าสู่โมเดลได้ในที่ที่รองรับ | ตรวจสอบรูปแบบ Schema, การตั้งชื่อ, การจัดกลุ่ม, การอ้างอิง และว่าโมเดลทุกตัวควรถูกนำเข้าหรือไม่ |
| Stoplight ID | Stoplight ID ระดับ root อาจช่วย Apidog จับคู่โมดูลที่นำเข้าในการซิงค์ | อย่าสันนิษฐานว่าอัตลักษณ์ระดับ Endpoint หรือระดับหน้าจะถูกเก็บรักษาไว้ทั้งหมด |
หมายเหตุความเข้ากันได้สำหรับไฟล์โปรเจกต์ Stoplight
.stoplight.jsonควรถือเป็นชุดย่อยของการกำหนดค่าเส้นทางที่รองรับสำหรับการซิงค์ Apidog สามารถใช้ไดเรกทอรี root ที่รองรับสำหรับ OpenAPI, Markdown และ JSON Schema, รูปแบบการรวม OpenAPI, รูปแบบการยกเว้นทั่วโลก และtocPathการตั้งค่าโปรเจกต์ Stoplight อื่นๆ ควรถือว่าถูกละเว้นเว้นแต่จะได้รับการยืนยันtoc.jsonสามารถช่วยสร้างความหมายของการนำทางที่รองรับใน Apidog ใหม่ รวมถึงโฟลเดอร์ DOCS, การจัดเรียง Markdown, ลิงก์ OAS/โมดูล, ลิงก์รายการ Spec ที่เลือก และการนำเข้าโมเดลที่อ้างอิงใน TOC แถบด้านข้างสุดท้ายยังคงแสดงผลผ่านโมเดล DOCS/OAS/MODELS ของ Apidog ดังนั้นโครงร่าง Stoplight ที่ไม่แน่นอนและการจัดเรียงข้ามประเภทที่ไม่จำเพาะเจาะจงอาจไม่ได้รับการเก็บรักษาไว้toc.jsonไม่ได้ปรับแต่งแถบด้านข้างเอกสารออนไลน์สุดท้ายได้อย่างสมบูรณ์- รูปภาพจะถูกย้ายข้อมูลเป็นหลักเมื่อถูกอ้างอิงโดย Markdown สินทรัพย์ที่ไม่ได้อ้างอิง, รูปภาพภายนอก และ data URI ควรได้รับการตรวจสอบแยกต่างหาก
- ไฟล์ JSON Schema คาดเดาได้มากที่สุดเมื่อถูกอ้างอิงอย่างชัดเจนโดยโครงสร้างโปรเจกต์ที่รองรับ เช่น
toc.jsonมากกว่าที่จะสันนิษฐานจากไดเรกทอรีเพียงอย่างเดียว
สิ่งนี้ทำให้ทีมมีจุดเริ่มต้นที่เป็นรูปธรรม: ใช้ไฟล์โปรเจกต์ที่มีอยู่เพื่อสร้างพื้นที่ทำงาน API ให้ได้มากที่สุดเท่าที่จะทำได้ จากนั้นตรวจสอบส่วนที่ขึ้นอยู่กับพฤติกรรมเฉพาะของ Stoplight เป้าหมายไม่ใช่การสร้าง Stoplight ขึ้นมาใหม่แบบพิกเซลต่อพิกเซล แต่เป็นการรักษาสภาพแวดล้อมของโปรเจกต์ที่ใช้ไฟล์เป็นหลักและเชื่อมต่อเข้ากับวงจรชีวิต API ที่กว้างขึ้น
จากการนำเข้าไฟล์สู่เวิร์กโฟลว์ API ที่เชื่อมต่อกัน
ในเวิร์กโฟลว์การนำเข้าแบบดั้งเดิม ทีมมักจะนำเข้าไฟล์ OpenAPI เพียงครั้งเดียว จากนั้นก็ทำงานต่อด้วยภาพในเครื่องมือใหม่ ซึ่งอาจทำให้เกิดความคลาดเคลื่อน: ไฟล์ใน Git, เอกสาร และพื้นที่ทำงาน API อาจไม่แสดงถึงแหล่งข้อมูลที่ถูกต้องที่สุดเดียวกันอีกต่อไป
Spec-first Mode แตกต่างออกไป ไฟล์ยังคงเป็นรากฐาน
ในโปรเจกต์ Spec-first ที่เชื่อมต่อกับ Git ทีมสามารถแก้ไขไฟล์ในพื้นที่ทำงาน Specs จากนั้น commit และ push การเปลี่ยนแปลงกลับไปยัง Repository ในโปรเจกต์ที่ใช้ไฟล์เป็นหลัก ทีมสามารถแก้ไขและบันทึกไฟล์ Spec ภายใน Apidog ก่อนที่จะเชื่อมต่อ Git
การแบ่งแยกในทางปฏิบัติคือ:
| ความรับผิดชอบ | แหล่งที่มาที่แนะนำ |
|---|---|
| สัญญา API | ไฟล์ OpenAPI / Swagger |
| โครงสร้างไฟล์โปรเจกต์ | Repository หรือโครงสร้างโปรเจกต์ที่ใช้ไฟล์เป็นหลัก |
| การตั้งค่าเส้นทางสไตล์ Stoplight ที่รองรับ | .stoplight.json |
| อินพุตการนำทางเอกสารที่รองรับ | toc.json และเอกสาร Markdown |
| การทำงานร่วมกัน API รายวัน | พื้นที่ทำงานโปรเจกต์ Apidog |
| ม็อค, การทดสอบ, รายงาน และสิทธิ์ทีม | เวิร์กโฟลว์แพลตฟอร์ม Apidog ที่กว้างขึ้น |
นี่คือคุณค่าหลักของการย้ายข้อมูล: ทีมสามารถรักษารูปแบบสัญญาที่ใช้ไฟล์เป็นหลัก ในขณะที่ให้ผู้มีส่วนได้ส่วนเสียมากขึ้นมีพื้นที่ทำงาน API ที่ใช้งานได้รอบสัญญานั้น
นั่นคือความแตกต่างระหว่างการย้ายข้อมูลกับการย้ายเวิร์กโฟลว์ การนำเข้าไฟล์เป็นการย้ายสัญญาเพียงครั้งเดียว การเชื่อมต่อโปรเจกต์ Spec-first ให้พื้นที่ทำงานแก่ทีมรอบสัญญา
เส้นทางการย้ายข้อมูลแบบ Git-Connected vs File-Backed
ทีม Stoplight ไม่ได้เริ่มต้นจากระดับความสมบูรณ์ของเวิร์กโฟลว์เดียวกันทั้งหมด
บางทีมได้ตรวจสอบการเปลี่ยนแปลง API ทุกครั้งผ่าน Git branches และ pull requests แล้ว ในขณะที่ทีมอื่นมี Spec API และเอกสารเป็นไฟล์ แต่ยังไม่พร้อมที่จะทำให้ผู้ให้บริการ Git ภายนอกเป็นส่วนหนึ่งของการเปิดตัวครั้งแรก
Apidog Spec-first Mode รองรับทั้งสองเส้นทาง
| เส้นทาง | เหมาะที่สุดสำหรับ | เวิร์กโฟลว์ทั่วไป |
|---|---|---|
| โปรเจกต์ Spec-first ที่เชื่อมต่อกับ Git | ทีมที่จัดการ Spec OpenAPI ใน Git อยู่แล้ว | เชื่อมต่อ Repository, ซิงค์ Branch, แก้ไขไฟล์, commit และ push |
| โปรเจกต์ Spec-first ที่ใช้ไฟล์เป็นหลัก | ทีมที่ต้องการการออกแบบ API ที่ใช้ไฟล์เป็นหลักก่อนเชื่อมต่อ Git | ทำงานกับไฟล์ Spec ใน Apidog, บันทึกการเปลี่ยนแปลง และตรวจสอบความถูกต้องของเวิร์กโฟลว์ก่อน |
สำหรับการย้ายข้อมูล Stoplight ส่วนใหญ่ โปรเจกต์ที่เชื่อมต่อกับ Git เป็นโมเดลระยะยาวที่ชัดเจนกว่า เนื่องจาก Repository ยังคงเป็นแหล่งข้อมูลที่ถูกต้องที่สุดของสัญญา API
โปรเจกต์ที่ใช้ไฟล์เป็นหลักมีประโยชน์เมื่อทีมต้องการประเมินประสบการณ์การเขียน, ทำความสะอาดไฟล์โปรเจกต์ หรือจัดเตรียมการย้ายข้อมูลก่อนที่จะนำเวิร์กโฟลว์ Git ที่เข้มงวดมากขึ้นมาใช้
สิ่งที่ควรตรวจสอบหลังการย้ายข้อมูล
แม้ว่าไฟล์โปรเจกต์จะสามารถโอนย้ายได้ การย้ายข้อมูลควรรวมถึงขั้นตอนการตรวจสอบด้วย สิ่งนี้สำคัญอย่างยิ่งสำหรับทีมที่มีเว็บไซต์เอกสารขนาดใหญ่, ไฟล์ Schema จำนวนมาก หรือการนำทาง Stoplight ที่ปรับแต่งเอง
ใช้รายการตรวจสอบนี้หลังจากสร้างโปรเจกต์ Spec-first
| พื้นที่ | สิ่งที่ต้องตรวจสอบ |
|---|---|
| โมดูล OpenAPI | ยืนยันว่าไฟล์ Spec ที่ตั้งใจไว้ทั้งหมดถูกนำเข้าแล้ว, ชื่อโมดูลถูกต้อง และ Endpoints ถูกจัดกลุ่มตามที่คาดไว้ |
| การอ้างอิงภายนอก | ตรวจสอบว่าการพึ่งพา $ref ได้รับการแก้ไขตามที่คาดไว้หรือไม่ และมีปัญหาการแปลงใดๆ รายงานหรือไม่ |
| Lint / การตรวจสอบความถูกต้อง | รันการตรวจสอบ Apidog Specs บนไฟล์ OpenAPI ที่นำเข้า Apidog สามารถใช้ .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs ระดับ root และสามารถใช้ .stoplight/styleguide.json เป็นทางเลือกสำหรับการตรวจสอบความถูกต้องของ Editor ที่ใช้ Spectral ถือผลการค้นหาเป็นสัญญาณการตรวจสอบ ไม่ใช่การย้ายข้อมูลการกำกับดูแล Style Guide ของ Stoplight เต็มรูปแบบ |
.stoplight.json | ยืนยัน Root ของ OpenAPI, Markdown และ JSON Schema ที่รองรับ, รูปแบบการรวม OpenAPI, รูปแบบการยกเว้นทั่วโลก และ tocPath ยืนยันผลลัพธ์การนำเข้าจริงแทนที่จะสันนิษฐานว่าฟิลด์การกำหนดค่า Stoplight ทุกตัวถูกนำไปใช้ |
toc.json | ตรวจสอบกลุ่มที่รองรับ, ตัวแบ่ง, ชื่อ, การกรองและจัดเรียง Markdown, กลุ่มที่สามารถคลิกได้, ลิงก์ OAS/โมดูล, ลิงก์รายการ Spec ที่เลือก, การนำเข้าโมเดลที่อ้างอิงใน TOC และผลลัพธ์แถบด้านข้าง Apidog สุดท้าย |
| เอกสาร Markdown | ตรวจสอบการจัดรูปแบบ, หัวข้อ, ลิงก์สัมพัทธ์, แองเคอร์ และลิงก์ไปยังไฟล์ API หรือการดำเนินการ |
| รูปภาพ | ยืนยันว่ารูปภาพภายในเครื่องที่อ้างอิงแสดงผลได้อย่างถูกต้อง ตรวจสอบรูปภาพภายนอก, data URI, การอ้างอิงที่เสียหาย และสินทรัพย์ที่ไม่ได้ใช้งานแยกต่างหาก |
| โมเดล | ยืนยันว่าไฟล์ JSON Schema ที่อ้างอิงโดย toc.json กลายเป็นทรัพยากรโมเดลใด และชื่อ, โฟลเดอร์ และการอ้างอิงถูกต้องหรือไม่ |
| Stoplight ID | ยืนยันว่าการจับคู่โมดูลทำงานได้ตามที่คาดไว้ในการซิงค์ซ้ำๆ อย่าพึ่งพา ID เพียงอย่างเดียวสำหรับทุกประเภททรัพยากร |
| การทดสอบและม็อค | สร้างใหม่หรือเชื่อมต่อสถานการณ์ที่เคยดูแลอยู่ใน Postman, Bruno, CI หรือเครื่องมือแยกต่างหาก |
| สิทธิ์และการเผยแพร่ | สร้างการเข้าถึงทีม, การมองเห็นเอกสาร, กฎการตรวจสอบ และความรับผิดชอบในการเผยแพร่ใหม่ในพื้นที่ทำงานใหม่ |
การตรวจสอบนี้ไม่ใช่การแก้ปัญหาเฉพาะหน้า เป็นความแตกต่างปกติระหว่างการย้ายไฟล์กับการย้ายประสบการณ์เฉพาะผลิตภัณฑ์ทั้งหมด
แล้วสินทรัพย์ Postman และ Bruno ล่ะ?
ทีม Stoplight หลายทีมยังใช้ Postman หรือ Bruno สินทรัพย์เหล่านั้นควรได้รับการวางแผนแยกต่างหากจากการย้ายข้อมูล OpenAPI
ไฟล์ OpenAPI กำหนดสัญญา API คอลเลกชัน Postman และไฟล์ .bru ของ Bruno มักจะกำหนดเวิร์กโฟลว์คำขอ, ตัวอย่าง, สภาพแวดล้อม หรือการทดสอบ สิ่งเหล่านี้มีค่า แต่ไม่ใช่วัตถุการย้ายข้อมูลเดียวกับโปรเจกต์ OpenAPI สไตล์ Stoplight
ก่อนการย้ายข้อมูล ให้ตอบคำถามเหล่านี้:
| คำถาม | ทำไมจึงสำคัญ |
|---|---|
| OpenAPI เป็นแหล่งข้อมูลที่ถูกต้องที่สุด หรือคอลเลกชันเป็นตัวขับเคลื่อนพฤติกรรม API จริง? | การย้ายข้อมูลแบบ Spec-first ควรสิ้นสุดที่สัญญาที่เชื่อถือได้ |
| ตัวอย่างคำขอใดที่ยังคงมีความสำคัญ? | สร้างตัวอย่างที่สำคัญใหม่รอบพื้นที่ทำงาน API ที่เชื่อมต่อแล้ว |
| การทดสอบใดที่ควรดำเนินการต่อไป? | ย้ายหรือเชื่อมต่อการทดสอบ API ไปยังเวิร์กโฟลว์ใหม่ แทนที่จะสันนิษฐานว่าการย้ายจะมาพร้อมกับเอกสาร |
| สภาพแวดล้อมและความลับใดบ้างที่ใช้ร่วมกัน? | วางแผนการจัดการสภาพแวดล้อมแยกต่างหากจากการย้าย Spec |
| งาน CI ใดที่ขึ้นอยู่กับเครื่องมือปัจจุบัน? | เชื่อมต่อการตรวจสอบความถูกต้อง, การทดสอบ และการรายงานอย่างตั้งใจ |
สำหรับผู้ใช้ Bruno ข้อมูลเชิงลึกที่สำคัญคือเวิร์กโฟลว์แบบ Git-native มีคุณค่าอยู่แล้ว Spec-first Mode สามารถรักษาสัญญา API ให้เป็นแบบไฟล์ได้ แต่สินทรัพย์ Bruno อาจยังคงต้องการการย้ายข้อมูล, การสร้างใหม่ หรือการเปลี่ยนแยกต่างหาก ขึ้นอยู่กับว่าทีมใช้งานอย่างไร
แผนการย้ายข้อมูลที่แนะนำ
ให้ใช้แผนการแบบแบ่งขั้นตอนแทนที่จะพยายามย้ายเวิร์กโฟลว์ API ทั้งหมดในครั้งเดียว
แผนการย้ายข้อมูลแบบแบ่งขั้นตอน: ย้ายสัญญา OpenAPI ก่อน จากนั้นจึงเชื่อมต่อเวิร์กโฟลว์โดยรอบ
1. ตรวจสอบ Repository สไตล์ Stoplight
ระบุไฟล์ OpenAPI, .stoplight.json, toc.json, เอกสาร Markdown, โมเดล, รูปภาพ และสินทรัพย์คำขอหรือการทดสอบที่เกี่ยวข้องใดๆ
2. ตัดสินใจแหล่งข้อมูลที่ถูกต้องที่สุด
ยืนยันว่าไฟล์ OpenAPI ใน Git เป็นแหล่งที่มาของสัญญาหรือไม่ หากเครื่องมือหรือคอลเลกชันอื่นเป็นแหล่งข้อมูลที่ถูกต้องที่สุด ให้แก้ไขสิ่งนั้นก่อนการย้ายข้อมูล
3. สร้างโปรเจกต์ Spec-first
เลือกโปรเจกต์ที่เชื่อมต่อกับ Git หากทีมพร้อมที่จะใช้ Git เป็นแหล่งข้อมูลที่ถูกต้องที่สุด เลือกโปรเจกต์ที่ใช้ไฟล์เป็นหลัก หากทีมต้องการตรวจสอบเวิร์กโฟลว์ไฟล์ก่อน
4. ตรวจสอบสิ่งที่โอนย้ายมา
ตรวจสอบโมดูล, เอกสาร, โมเดล, รูปภาพที่อ้างอิง, ลิงก์, อินพุตการนำทาง toc.json ที่รองรับ, การตั้งค่าเส้นทาง .stoplight.json ที่รองรับ และผลลัพธ์การตรวจสอบ Spec แก้ไขไฟล์โปรเจกต์ในที่ที่ทำได้ แทนที่จะแก้ไขอาการด้วยตนเอง
5. สร้างสินทรัพย์ระดับเวิร์กโฟลว์ใหม่
เชื่อมต่อม็อค, การทดสอบ, ตัวอย่างคำขอ, งาน CI, รายงาน, สิทธิ์ และความรับผิดชอบในการเผยแพร่ใหม่รอบสัญญา API ที่ย้ายข้อมูลแล้ว
6. ดำเนินการเปลี่ยนแปลงจริงครั้งแรกผ่านเวิร์กโฟลว์ใหม่
ทำการเปลี่ยนแปลง OpenAPI เล็กน้อย, ตรวจสอบ, ซิงค์, อัปเดตเอกสารหากจำเป็น และตรวจสอบว่าม็อค, การทดสอบ และรายงานที่เกี่ยวข้องทำงานได้ตามที่คาดไว้
หากทีมของคุณดูแลไฟล์ OpenAPI, เอกสาร Markdown และโมเดล Schema ใน Repository สไตล์ Stoplight อยู่แล้ว Apidog Spec-first Mode สามารถช่วยคุณทดสอบเส้นทางการย้ายข้อมูลก่อนที่จะสร้างเวิร์กโฟลว์ทั้งหมดขึ้นมาใหม่
เส้นทางการย้ายข้อมูลนี้เหมาะสมที่สุดเมื่อใด
เส้นทางการย้ายข้อมูลนี้เหมาะสมอย่างยิ่งเมื่อ:
- ทีมของคุณจัดการ Spec OpenAPI หรือ Swagger เป็นไฟล์;
- โปรเจกต์ Stoplight ของคุณมีเอกสาร Markdown, โมเดล, รูปภาพ,
.stoplight.jsonหรือtoc.json; - กระบวนการตรวจสอบ API ของคุณขึ้นอยู่กับ Git branches หรือ pull requests อยู่แล้ว;
- คุณต้องการให้เอกสาร API, ม็อค, การทดสอบ, รายงาน และการทำงานร่วมกันยังคงเชื่อมต่อกับสัญญา API;
- คุณต้องการลดความคลาดเคลื่อนระหว่างไฟล์ API และพื้นที่ทำงานที่ใช้โดยทีม Frontend, QA, ผลิตภัณฑ์, แพลตฟอร์ม หรือพันธมิตร
อาจต้องมีการวางแผนมากขึ้นเมื่อ:
- แหล่งข้อมูลที่ถูกต้องที่สุดของ API จริงคือคอลเลกชัน Postman หรือ Bruno แทนที่จะเป็น OpenAPI;
- โปรเจกต์ Stoplight อาศัยพฤติกรรมการเผยแพร่ที่กำหนดเองอย่างมาก;
- เอกสารประกอบมีลิงก์ภายนอก, แองเคอร์, หน้าที่สร้างขึ้น หรือสินทรัพย์ที่ไม่ได้อ้างอิงจำนวนมาก;
- โมเดล JSON Schema ถูกจัดเก็บในรูปแบบหรือโครงสร้างที่ต้องการการตรวจสอบด้วยตนเอง;
- ทีมต้องการสร้างการนำทาง Stoplight หรือการแสดงผลเอกสารขึ้นมาใหม่ให้สมบูรณ์แบบระดับพิกเซล
คำถามที่พบบ่อย
Apidog Spec-first Mode เป็นทางเลือกของ Stoplight หรือไม่?
สามารถใช้เป็นทางเลือกของ Stoplight สำหรับทีมที่ต้องการให้โปรเจกต์ OpenAPI เป็นแบบไฟล์ในขณะที่เพิ่มการทำงานร่วมกัน API, การทดสอบ, การจำลอง, เอกสาร, การรายงาน และการจัดการสิทธิ์ที่กว้างขึ้นรอบไฟล์เหล่านั้น
ฉันสามารถเก็บ Spec OpenAPI ไว้ใน Git ได้หรือไม่?
ได้ ในโปรเจกต์ Spec-first ที่เชื่อมต่อกับ Git ทีมสามารถใช้ Git เป็นแหล่งข้อมูลที่ถูกต้องที่สุด, ซิงค์ Branch, แก้ไขไฟล์ และ commit การเปลี่ยนแปลงกลับไปยัง Repository
ฉันจำเป็นต้องมี Git เพื่อเริ่มต้นหรือไม่?
ไม่จำเป็น โปรเจกต์ Spec-first ที่ใช้ไฟล์เป็นหลักสามารถใช้ได้เมื่อทีมต้องการทำงานกับไฟล์ Spec ก่อนแล้วค่อยเชื่อมต่อ Git ในภายหลัง
.stoplight.json และ toc.json จะถูกเก็บรักษาไว้ทั้งหมดหรือไม่?
ไม่ Apidog ใช้ส่วนที่รองรับของไฟล์เหล่านี้เป็นอินพุตการย้ายข้อมูล .stoplight.json ใช้เป็นหลักสำหรับการค้นหาเส้นทางระหว่างการซิงค์ รวมถึง Root ของ OpenAPI, Markdown, JSON Schema ที่รองรับ, รูปแบบการรวม OpenAPI, การยกเว้นทั่วโลก และ tocPath toc.json สามารถช่วยจัดระเบียบเนื้อหา DOCS ที่รองรับ, ลิงก์ OAS/โมดูล, ลิงก์รายการ Spec ที่เลือก และการนำเข้าโมเดลที่อ้างอิงใน TOC แถบด้านข้างเอกสารออนไลน์สุดท้ายยังคงถูกจำกัดโดยโมเดล DOCS/OAS/MODELS ของ Apidog ดังนั้นการนำทาง Stoplight ที่แน่นอนและการจัดเรียงข้ามประเภทที่ไม่จำเพาะเจาะจงอาจไม่ได้รับการเก็บรักษาไว้
เกิดอะไรขึ้นกับเอกสาร Markdown?
เอกสาร Markdown สามารถนำเข้าสู่เวิร์กโฟลว์โปรเจกต์ Spec-first ได้ เมื่อมี toc.json เอกสารที่ระบุใน TOC สามารถรักษาสิ่งก่อสร้างได้มากขึ้นในที่ที่รองรับ ควรตรวจสอบลิงก์ภายใน, แองเคอร์, รูปภาพ และการแสดงผลอีกครั้ง
เกิดอะไรขึ้นกับโมเดล JSON Schema?
โมเดล JSON Schema สามารถโอนย้ายได้ในที่ที่รองรับเมื่อถูกอ้างอิงอย่างชัดเจนโดยโครงสร้างโปรเจกต์ที่รองรับ เช่น toc.json อย่าสันนิษฐานว่าไฟล์ JSON ทุกไฟล์ในไดเรกทอรี models จะกลายเป็นทรัพยากรโมเดลโดยอัตโนมัติ ตรวจสอบรูปแบบ Schema, ชื่อ, โฟลเดอร์ และการอ้างอิงหลังการย้ายข้อมูล
เกิดอะไรขึ้นกับรูปภาพ?
รูปภาพภายในเครื่องที่อ้างอิงโดย Markdown สามารถนำเข้าได้ในที่ที่รองรับ อย่าถือว่า formats.image.rootDir เป็นการรับประกันว่าไฟล์รูปภาพทุกไฟล์ในไดเรกทอรีนั้นจะถูกนำเข้า รูปภาพภายนอก, data URI, การอ้างอิงที่เสียหาย และไฟล์รูปภาพที่ไม่ได้ใช้งานควรได้รับการตรวจสอบแยกต่างหาก
ฉันควรรัน lint หรือการตรวจสอบความถูกต้องหลังการย้ายข้อมูลหรือไม่?
ได้ หลังจากการย้ายข้อมูล ให้รันการตรวจสอบ Spec บนไฟล์ OpenAPI ที่นำเข้า Apidog รองรับการตรวจสอบความถูกต้องของ Editor ที่ใช้ Spectral และสามารถอ่าน .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs ระดับ root หรือใช้ .stoplight/styleguide.json เป็นทางเลือก ใช้ผลลัพธ์เพื่อตรวจสอบปัญหาสัญญาและสไตล์; อย่าถือว่าการตรวจสอบสำเร็จเป็นหลักฐานว่าพฤติกรรมเฉพาะของ Stoplight ทุกอย่างได้รับการเก็บรักษาไว้
ผู้ใช้ Bruno หรือ Postman ควรทำอย่างไร?
ขั้นแรก ให้ระบุว่า OpenAPI หรือคอลเลกชันเป็นแหล่งข้อมูลที่ถูกต้องที่สุด การย้ายข้อมูลแบบ Spec-first มุ่งเน้นไปที่ OpenAPI และไฟล์โปรเจกต์ที่เกี่ยวข้อง เวิร์กโฟลว์คำขอ, สภาพแวดล้อม และการทดสอบที่ใช้คอลเลกชันอาจต้องการการย้ายข้อมูลหรือการสร้างใหม่แยกต่างหาก
Apidog ยังรองรับม็อค, การทดสอบ, CI/CD, รายงาน และการทำงานร่วมกันด้วยหรือไม่?
ได้ Spec-first Mode เชื่อมต่อสัญญา API ที่ใช้ไฟล์เป็นหลักเข้ากับ Apidog และแพลตฟอร์ม Apidog ที่กว้างขึ้นสามารถรองรับเอกสาร, ม็อค, สถานการณ์การทดสอบ, การดำเนินการ CI/CD ด้วย Apidog CLI, รายงาน, สิทธิ์ และการทำงานร่วมกันเป็นทีมรอบสัญญานั้น
บทสรุป
การย้ายข้อมูล Stoplight ไม่ควรหมายถึงการละทิ้งการทำงาน API ที่ใช้ไฟล์เป็นหลัก
Repository ยังคงเป็นแหล่งข้อมูลที่ถูกต้องที่สุด รายละเอียด OpenAPI, เอกสาร Markdown, รูปภาพที่อ้างอิง, โมเดล JSON Schema ที่อ้างอิงใน TOC และไฟล์โครงสร้างโปรเจกต์ที่รองรับสามารถพกพาและตรวจสอบได้ ในขณะเดียวกัน เวิร์กโฟลว์ API รอบไฟล์เหล่านั้นสามารถเชื่อมต่อกันได้มากขึ้น
Apidog Spec-first Mode มอบเส้นทางการย้ายข้อมูลที่ใช้งานได้จริงให้แก่ทีม Stoplight: โอนย้ายส่วนที่เป็นไฟล์ของโปรเจกต์ในที่ที่รองรับ, ตรวจสอบโครงสร้างเฉพาะของ Stoplight อย่างรอบคอบ และสร้างสินทรัพย์ระดับเวิร์กโฟลว์ใหม่รอบพื้นที่ทำงาน API ที่เชื่อมต่อแล้ว
หากทีมของคุณกำลังประเมินการย้ายข้อมูล Stoplight ให้เริ่มต้นด้วยการตรวจสอบโครงสร้าง Repository ของคุณและตัดสินใจว่าไฟล์ใดเป็นตัวกำหนดสัญญา API จากนั้นใช้ Spec-first Mode เพื่อเชื่อมต่อไฟล์เหล่านั้นกับเอกสาร, ม็อค, การทดสอบ, รายงาน, สิทธิ์ และการทำงานร่วมกันใน Apidog
สำหรับการวางแผนการย้ายข้อมูลระดับองค์กร โปรดดู Apidog Enterprise