สรุปย่อ
ความขัดแย้งในการซิงค์ของ SwaggerHub เกิดขึ้นเมื่อมีการแก้ไขพร้อมกัน หรือการรวม Git ทำให้เกิดเวอร์ชันของสเปกที่ขัดแย้งกัน การแก้ไขเกี่ยวข้องกับการระบุเวอร์ชันที่ขัดแย้งกัน การรวมการเปลี่ยนแปลงด้วยตนเอง และการคอมมิตใหม่ การป้องกันดีกว่าการแก้ไข – การเป็นเจ้าของที่ชัดเจน การมีวินัยในการใช้ branch และข้อตกลงในการล็อกช่วยลดความขัดแย้งส่วนใหญ่ก่อนที่จะเกิดขึ้น โมเดลการสร้าง branch ของ Apidog ช่วยลดความขัดแย้งในการแก้ไขพร้อมกันโดยการออกแบบ
บทนำ
คุณสมบัติการแก้ไขร่วมกันของ SwaggerHub มีประโยชน์อย่างแท้จริง สมาชิกในทีมหลายคนสามารถทำงานบนคำจำกัดความ API เดียวกันได้ การเปลี่ยนแปลงสามารถมองเห็นได้เกือบจะเรียลไทม์ และการรวม Git ช่วยให้ทีมสามารถซิงโครไนซ์สเปกกับที่เก็บซอร์สโค้ดของพวกเขาได้
แต่การทำงานร่วมกันทำให้เกิดความขัดแย้ง วิศวกรสองคนแก้ไข endpoint เดียวกันพร้อมกัน สเปกถูกอัปเดตใน SwaggerHub และแยกต่างหากใน GitHub และกระบวนการซิงค์พบเวอร์ชันที่แตกต่างกัน Domain ถูกอัปเดตในขณะที่ API อยู่ระหว่างการตรวจสอบ ความขัดแย้งเหล่านี้สามารถจัดการได้ แต่ก็ก่อกวนเมื่อเกิดขึ้นโดยไม่คาดคิดและทีมไม่มีกระบวนการแก้ไขที่ชัดเจน
คู่มือนี้อธิบายประเภทของความขัดแย้งที่เกิดขึ้นใน SwaggerHub วิธีแก้ไขแต่ละประเภท และวิธีป้องกันด้วยวินัยการทำงานที่ดีขึ้น ส่วนสุดท้ายครอบคลุมถึงวิธีที่ Apidog จัดการกับปัญหาประเภทเดียวกัน
ประเภทของความขัดแย้งในการซิงค์ใน SwaggerHub
1. ความขัดแย้งในการแก้ไขพร้อมกัน (Concurrent editing conflicts) SwaggerHub อนุญาตให้ผู้ใช้หลายคนแก้ไขคำจำกัดความ API ได้พร้อมกัน เมื่อผู้ใช้สองคนแก้ไขส่วนเดียวกันของสเปกพร้อมกัน การบันทึกครั้งสุดท้ายจะเป็นผู้ชนะ ไม่มีการรวม — การบันทึกครั้งที่สองจะเขียนทับการเปลี่ยนแปลงของผู้ใช้คนแรก ซึ่งในทางเทคนิคแล้วไม่ใช่ “ความขัดแย้ง” ในความหมายของ Git (ไม่มีสถานะข้อผิดพลาด) แต่มันทำให้ข้อมูลสูญหายหากทีมไม่ระมัดระวัง
2. ความขัดแย้งในการซิงค์ระหว่าง SwaggerHub กับ Git (SwaggerHub-to-Git sync conflicts) SwaggerHub สามารถรวมเข้ากับ GitHub, GitLab และ Bitbucket ได้ เมื่อสเปกถูกบันทึกใน SwaggerHub มันสามารถ auto-push ไปยัง repository ที่กำหนดค่าไว้ได้ เมื่อไฟล์สเปกถูก commit โดยตรงไปยัง repository มันสามารถซิงค์กลับไปยัง SwaggerHub ได้ หากทั้งสองอย่างเกิดขึ้นอย่างอิสระ คุณจะได้รับเวอร์ชันที่ขัดแย้งกันซึ่งกระบวนการซิงค์ของ SwaggerHub ไม่สามารถประนีประนอมได้โดยอัตโนมัติ
3. ความขัดแย้งในการแยกเวอร์ชัน API (API version fork conflicts) เมื่อคุณแยกเวอร์ชัน API ใน SwaggerHub เพื่อสร้าง working branch ใหม่ จากนั้นพยายามรวมการเปลี่ยนแปลงกลับไป ความแตกต่างระหว่าง branch ที่แยกออกมากับต้นฉบับสามารถสร้างความขัดแย้งที่ต้องแก้ไขด้วยตนเอง
4. ความขัดแย้งของเวอร์ชัน Domain ที่ไม่ตรงกัน (Domain version mismatch conflicts) หาก API อ้างอิง SwaggerHub Domain ที่เวอร์ชันเฉพาะ และเวอร์ชัน Domain นั้นถูกยกเลิกหรือแก้ไขโดยไม่เข้ากัน API ที่อ้างอิงอาจพบข้อผิดพลาดในการแก้ไข นี่ไม่ใช่ความขัดแย้งในการซิงค์โดยเฉพาะ แต่มันทำให้เกิดการหยุดชะงักที่คล้ายกันและต้องการขั้นตอนการแก้ไขที่คล้ายกัน
5. ความขัดแย้งในการดึง Git ใน repository ที่เชื่อมต่อ (Git pull conflicts in connected repositories) เมื่อ Git repository ที่เชื่อมต่อกับ SwaggerHub มี branch หรือการรวมที่ส่งผลให้เกิดความขัดแย้งในไฟล์สเปก กระบวนการซิงค์ของ SwaggerHub จะแสดงความขัดแย้งเหล่านั้นเมื่อซิงค์ครั้งถัดไป
การแก้ไขความขัดแย้งในการแก้ไขพร้อมกัน
“ความขัดแย้ง” ประเภทนี้เป็นสิ่งที่พบได้บ่อยที่สุดและมองไม่เห็นมากที่สุด ไม่มีข้อความแสดงข้อผิดพลาด — การเปลี่ยนแปลงของผู้ใช้คนหนึ่งจะหายไป
การแก้ไข:
- หากคุณสังเกตเห็นว่าการเปลี่ยนแปลงหายไปหลังจากสมาชิกในทีมคนอื่นบันทึก ให้ตรวจสอบประวัติการเปลี่ยนแปลงของ SwaggerHub (หากมีในแผนของคุณ) เพื่อดูว่ามีอะไรถูกเขียนทับไปบ้าง
- ขอให้สมาชิกในทีมที่บันทึกครั้งสุดท้ายเปรียบเทียบสถานะสเปกปัจจุบันกับสำเนาในเครื่องของพวกเขา
- ป้อนการเปลี่ยนแปลงที่หายไปซ้ำด้วยตนเอง
การป้องกันเป็นทางออกเดียวที่แท้จริง ดูส่วนการป้องกันด้านล่าง
การแก้ไขความขัดแย้งในการซิงค์ระหว่าง SwaggerHub กับ Git
เมื่อ SwaggerHub และ Git repository ของคุณมีความแตกต่างกัน คุณมักจะเห็นข้อผิดพลาดในการซิงค์ในแผงการรวม Git ของ SwaggerHub ซึ่งระบุว่าไม่สามารถ auto-push ได้เนื่องจาก remote มีการเปลี่ยนแปลงที่ไม่ได้อยู่ในเวอร์ชันของ SwaggerHub
ขั้นตอนการแก้ไข:
ขั้นตอนที่ 1: ดึงสเปกปัจจุบันจาก Git repository ของคุณ ดาวน์โหลดไฟล์ YAML หรือ JSON จาก branch ที่กำลังก่อให้เกิดความขัดแย้ง
ขั้นตอนที่ 2: ดึงสเปกปัจจุบันจาก SwaggerHub ส่งออก API เป็น YAML จาก SwaggerHub
ขั้นตอนที่ 3: เปรียบเทียบไฟล์ทั้งสอง ใช้เครื่องมือเปรียบเทียบใดๆ (diff, มุมมอง diff ของ VS Code หรือเครื่องมือ diff ที่รองรับ OpenAPI) ระบุว่ามีการเปลี่ยนแปลงใดบ้างที่มีอยู่ใน Git ที่ไม่มีใน SwaggerHub และในทางกลับกัน
ขั้นตอนที่ 4: รวมด้วยตนเอง สร้างเวอร์ชันสเปกที่ประนีประนอมซึ่งรวมการเปลี่ยนแปลงทั้งสองชุด สิ่งนี้ต้องใช้การตัดสินใจของมนุษย์ — เครื่องมือรวมอัตโนมัติอาจสร้าง YAML ที่ถูกต้องตามหลักไวยากรณ์แต่ผิดความหมาย
ขั้นตอนที่ 5: เลือกแหล่งข้อมูลที่น่าเชื่อถือแหล่งเดียว ตัดสินใจว่า SwaggerHub หรือ Git เป็นแหล่งข้อมูลที่เชื่อถือได้ จากนั้นอัปเดตอีกฝ่าย หาก Git เป็นแหล่งข้อมูลที่เชื่อถือได้ ให้ commit สเปกที่รวมแล้วไปยัง repository และให้การซิงค์ดึงเข้าไปใน SwaggerHub หาก SwaggerHub เป็นแหล่งข้อมูลที่เชื่อถือได้ ให้ push สเปกที่รวมแล้วจาก SwaggerHub ไปยัง Git
ขั้นตอนที่ 6: ตรวจสอบการซิงค์ หลังจากอัปเดต ให้ยืนยันว่าแผงการรวม Git ของ SwaggerHub แสดงสถานะการซิงค์ที่สะอาดปราศจากความขัดแย้ง
เครื่องมือที่มีประโยชน์: openapi-diff เครื่องมือ OpenAPI diff หลายตัวเปรียบเทียบเวอร์ชันสเปกในระดับความหมาย (การเพิ่ม endpoint, การเปลี่ยนแปลงฟิลด์, breaking vs. non-breaking changes) แทนที่จะเป็นแบบบรรทัดต่อบรรทัด เครื่องมืออย่าง oasdiff หรือ openapi-diff ให้ผลลัพธ์ที่ชัดเจนกว่า raw YAML diff
การแก้ไขความขัดแย้งของเวอร์ชัน Domain ที่ไม่ตรงกัน
หาก API ของคุณอ้างอิงเวอร์ชัน Domain ที่มีการเปลี่ยนแปลงหรือถูกยกเลิก:
ขั้นตอนที่ 1: ระบุว่า API ของคุณอ้างอิงเวอร์ชัน Domain ใด ดู URL $ref ในสเปกของคุณ — จะรวมหมายเลขเวอร์ชันไว้ด้วย
ขั้นตอนที่ 2: ตรวจสอบ changelog สำหรับเวอร์ชัน Domain ตรวจสอบว่ามีการเปลี่ยนแปลงอะไรบ้างระหว่างเวอร์ชันที่คุณปักหมุดไว้ปัจจุบันกับเวอร์ชันล่าสุด
ขั้นตอนที่ 3: ประเมินว่าการเปลี่ยนแปลงเป็นการเปลี่ยนแปลงที่ส่งผลกระทบต่อการทำงานหรือไม่ (breaking) การเพิ่มฟิลด์ทางเลือกใหม่ไม่ส่งผลกระทบ การลบฟิลด์ การเปลี่ยนประเภท หรือการเปลี่ยนชื่อคุณสมบัติเป็นการเปลี่ยนแปลงที่ส่งผลกระทบ
ขั้นตอนที่ 4: อัปเดตพาธ $ref ของ API ของคุณเพื่ออ้างอิงเวอร์ชัน Domain ใหม่ หากคุณตัดสินใจที่จะย้าย ตรวจสอบว่าสเปกยังคงถูกต้องหลังการอัปเดต
ขั้นตอนที่ 5: อัปเดตทีม หากการเปลี่ยนแปลง Domain ส่งผลกระทบต่อ API หลายตัว ให้ประสานงานการย้ายเพื่อให้ทุกทีมอัปเดตตามกำหนดเวลาเดียวกัน
การแก้ไขความขัดแย้งในการแยกเวอร์ชัน API
เมื่อรวมเวอร์ชัน API ที่แยกออกมากลับไปยังเวอร์ชันหลัก:
ขั้นตอนที่ 1: ส่งออกทั้ง branch ที่แยกออกมาและเวอร์ชันหลักเป็นไฟล์ YAML
ขั้นตอนที่ 2: เปรียบเทียบสเปกทั้งสองโดยใช้เครื่องมือ OpenAPI diff
ขั้นตอนที่ 3: ใน SwaggerHub editor ให้ใช้การเปลี่ยนแปลงจาก branch ที่แยกออกมาไปยังเวอร์ชันหลักด้วยตนเอง (หรือในทางกลับกัน ขึ้นอยู่กับสถานะสุดท้ายที่ต้องการ)
ขั้นตอนที่ 4: ตรวจสอบสเปกที่รวมแล้วใน SwaggerHub editor เพื่อยืนยันว่าไม่มีข้อผิดพลาดในการตรวจสอบ
ขั้นตอนที่ 5: ลบหรือเก็บ branch ที่แยกออกมาหากไม่จำเป็นแล้ว
การป้องกัน: ลดความขัดแย้งก่อนที่จะเกิดขึ้น
กำหนดขอบเขตความรับผิดชอบที่ชัดเจน มอบหมายส่วนต่างๆ ของสเปก API ขนาดใหญ่ให้กับสมาชิกในทีมที่แตกต่างกัน บุคคลหนึ่งเป็นเจ้าของ authentication endpoints อีกคนเป็นเจ้าของ resource endpoints พื้นที่แก้ไขที่ทับซ้อนกันคือจุดที่เกิดความขัดแย้งพร้อมกัน
ใช้ forking สำหรับการเปลี่ยนแปลงที่ไม่เล็กน้อย สำหรับการเปลี่ยนแปลงใดๆ ที่จะใช้เวลามากกว่าหนึ่งชั่วโมงหรือต้องการการตรวจสอบ ให้ fork เวอร์ชัน API ก่อนแก้ไข สิ่งนี้จะแยกงานของคุณออกจากเวอร์ชันหลักจนกว่าคุณจะพร้อมที่จะรวม
กำหนดโปรโตคอลการซิงค์ Git หากคุณใช้การรวม Git ให้ตัดสินใจและจัดทำเอกสารว่าทิศทางใดเป็นแหล่งข้อมูลที่น่าเชื่อถือ “SwaggerHub เป็นตัวแก้ไข; Git เป็นบันทึก” หรือ “Git เป็นแหล่งข้อมูลที่น่าเชื่อถือ; SwaggerHub ซิงค์จาก Git” — ไม่ใช่ทั้งสองพร้อมกันกับการแก้ไขอิสระในแต่ละด้าน
สื่อสารก่อนแก้ไขพื้นที่ที่ใช้ร่วมกัน ใช้ Slack, ระบบตั๋ว หรือคุณสมบัติความคิดเห็นของ SwaggerHub เพื่อส่งสัญญาณเมื่อคุณกำลังจะแก้ไขส่วนที่ผู้อื่นอาจต้องแตะด้วย การสื่อสารแบบ asynchronous ช่วยป้องกันการเขียนทับจากการแก้ไขพร้อมกันส่วนใหญ่
ปักหมุดการอ้างอิง Domain อย่างชัดเจน อ้างอิงเวอร์ชัน Domain ที่เฉพาะเจาะจงในพาธ $ref ของคุณเสมอ ไม่ใช่อ้างอิง “latest” ที่ลอยตัว สิ่งนี้ช่วยป้องกันการเปลี่ยนแปลงที่ส่งผลกระทบต่อการทำงานโดยอัตโนมัติจากการไหลเข้าสู่ API ของคุณโดยไม่มีการดำเนินการโดยเจตนา
ตั้งค่า auto-push อย่างระมัดระวัง การตั้งค่า auto-push-on-save ของ SwaggerHub อาจสะดวก แต่สร้างความเสี่ยงต่อความขัดแย้งหากสมาชิกในทีมกำลัง commit การเปลี่ยนแปลงสเปกโดยตรงใน Git repository ปิดใช้งาน auto-push หากคุณมีนักพัฒนาที่ทำการเปลี่ยนแปลงสเปกทั้งสองที่
Apidog จัดการกับปัญหาเดียวกันอย่างไร
โมเดลการทำงานร่วมกันของ Apidog สร้างขึ้นจากแนวคิดการสร้าง branch แบบ Git ซึ่งช่วยป้องกันรูปแบบความขัดแย้งส่วนใหญ่เหล่านี้ด้วยการออกแบบ
ไม่มีการเขียนทับพร้อมกัน ใน Apidog สมาชิกในทีมทำงานบน branch ที่แยกจากกัน วิศวกรที่สร้าง endpoint ใหม่จะสร้าง branch ทำงาน และเปิดคำขอตรวจสอบเมื่อเสร็จสิ้น วิศวกรอีกคนทำการเปลี่ยนแปลงอื่นโดยทำเช่นเดียวกันบน branch ที่แยกจากกัน การเปลี่ยนแปลงจะไม่ถูกรวมเข้ากับ main branch จนกว่าจะได้รับการตรวจสอบและอนุมัติ สิ่งนี้ช่วยขจัดปัญหาการเขียนทับแบบ “last save wins” ได้อย่างสมบูรณ์
มีระบบตรวจสอบในตัว เวิร์กโฟลว์การตรวจสอบและอนุมัติหมายความว่าการเปลี่ยนแปลงสเปกต้องผ่านขั้นตอนการตรวจสอบที่ชัดเจนก่อนที่จะส่งผลกระทบต่อ main branch หรือเอกสารที่ทีมปลายน้ำกำลังใช้งาน
การตรวจจับความขัดแย้งเมื่อรวม เมื่อสอง branch แก้ไข endpoint หรือ schema เดียวกัน กระบวนการรวมของ Apidog จะแสดงความขัดแย้งอย่างชัดเจน ทีมจะแก้ไขโดยเห็นภาพการเปลี่ยนแปลงทั้งสองชุดอย่างชัดเจน
เวิร์กโฟลว์แบบ local-first สำหรับทีมที่กังวลเกี่ยวกับความขัดแย้งในการซิงค์กับ Git repository ภายนอก เวิร์กโฟลว์แบบ local ของ Apidog ช่วยลดขอบเขตความเสียหาย — การเปลี่ยนแปลงจะได้รับการตรวจสอบในแพลตฟอร์มก่อนที่จะถูก commit ไปยัง Git
คำถามที่พบบ่อย
มี UI สำหรับการแก้ไขความขัดแย้งใน SwaggerHub หรือไม่? SwaggerHub ไม่มีอินเทอร์เฟซสำหรับแก้ไขความขัดแย้งแบบกราฟิกเหมือนเครื่องมือ Git GUI บางตัว การแก้ไขความขัดแย้งต้องทำด้วยตนเอง — ดาวน์โหลดทั้งสองเวอร์ชัน เปรียบเทียบภายนอก SwaggerHub และอัปโหลดเวอร์ชันที่แก้ไขแล้ว
เครื่องมือ OpenAPI diff ที่ดีที่สุดในการใช้ระหว่างการแก้ไขความขัดแย้งคืออะไร? oasdiff เป็นเครื่องมือ command-line ที่ได้รับการดูแลอย่างดี ซึ่งสร้าง diff ที่มีโครงสร้างของสเปก OpenAPI โดยระบุการเปลี่ยนแปลงที่ส่งผลกระทบ (breaking changes) แยกจากการเพิ่มที่ไม่ส่งผลกระทบ (non-breaking additions) ให้ผลลัพธ์ที่มีประโยชน์มากกว่า raw YAML diff สำหรับงานสเปก API
ฉันสามารถล็อก API ใน SwaggerHub เพื่อป้องกันไม่ให้ผู้อื่นแก้ไขได้หรือไม่? SwaggerHub ไม่มีกลไกการล็อกไฟล์ในตัว วิธีแก้ปัญหาที่ใกล้เคียงที่สุดคือการใช้ระบบบทบาทของ SwaggerHub เพื่อจำกัดสิทธิ์การแก้ไขชั่วคราวในขณะที่คุณทำการเปลี่ยนแปลง จากนั้นจึงกู้คืน
ฉันจะรู้ได้อย่างไรว่าเวอร์ชันใดของ API ที่ขัดแย้งกันนั้นถูกต้อง? ตรวจสอบบันทึกกิจกรรมของ SwaggerHub (หากแผนของคุณมี) เพื่อดูว่าใครทำการเปลี่ยนแปลงอะไรและเมื่อใด หากคุณใช้ Git ประวัติการ commit เป็นบันทึกที่เชื่อถือได้ หากทั้งสองไม่สรุปผล ให้ปรึกษาสมาชิกในทีมที่เกี่ยวข้องเพื่อสร้างความตั้งใจขึ้นมาใหม่
SwaggerHub จะแจ้งเตือนฉันเมื่อ Domain ที่ฉันพึ่งพาได้รับการอัปเดตหรือไม่? SwaggerHub สามารถแจ้งเตือนคุณเกี่ยวกับการอัปเดต Domain ผ่านระบบการแจ้งเตือนของมัน ไม่ว่าคุณจะกำหนดค่านี้ไว้หรือไม่ขึ้นอยู่กับการตั้งค่าการแจ้งเตือนของคุณ ตรวจสอบ Organization Settings > Notifications เพื่อกำหนดค่าการแจ้งเตือนสำหรับการเปลี่ยนแปลง Domain
การย้ายไปใช้ Apidog จะช่วยป้องกันความขัดแย้งในการซิงค์ทั้งหมดได้หรือไม่? การสร้าง branch ช่วยลดความถี่ของความขัดแย้งลงอย่างมาก แต่ไม่ได้ขจัดออกไปทั้งหมด สอง branch ที่แก้ไข endpoint เดียวกันยังคงต้องได้รับการประนีประนอมเมื่อมีการรวมกัน สิ่งที่การสร้าง branch ทำคือทำให้ความขัดแย้งเหล่านั้นมองเห็นได้และชัดเจน แทนที่จะเป็นการเขียนทับโดยเงียบ
ความขัดแย้งในการซิงค์ใน SwaggerHub ส่วนใหญ่เป็นปัญหาของเวิร์กโฟลว์ ไม่ใช่ปัญหาของผลิตภัณฑ์ การเป็นเจ้าของที่ชัดเจน การมีวินัยในการใช้ branch และโปรโตคอลการซิงค์ Git ที่กำหนดไว้จะช่วยป้องกันปัญหาส่วนใหญ่ก่อนที่จะเกิดขึ้น เมื่อเกิดความขัดแย้งขึ้น กระบวนการที่เป็นระบบ — ส่งออกทั้งสองเวอร์ชัน เปรียบเทียบด้วยเครื่องมือที่เหมาะสม รวมด้วยตนเอง ตรวจสอบความถูกต้อง และยืนยันการซิงค์ — จะช่วยแก้ไขได้อย่างน่าเชื่อถือ โมเดลการสร้าง branch ของ Apidog ช่วยลดความถี่ของความขัดแย้งโดยทำให้การทำงานพร้อมกันชัดเจน แต่เครื่องมือแก้ไขร่วมกันใดๆ ก็ได้รับประโยชน์จากวินัยพื้นฐานเดียวกัน