สรุป
ความขัดแย้งในการซิงค์ของ SwaggerHub เกิดขึ้นเมื่อมีการแก้ไขพร้อมกัน หรือการผสานรวม Git สร้างเวอร์ชันข้อมูลจำเพาะที่ขัดแย้งกัน การแก้ไขเกี่ยวข้องกับการระบุเวอร์ชันที่ขัดแย้งกัน การรวมการเปลี่ยนแปลงด้วยตนเอง และการคอมมิตซ้ำ การป้องกันดีกว่าการแก้ไข — การกำหนดความเป็นเจ้าของที่ชัดเจน วินัยในการจัดการสาขา (branch discipline) และข้อตกลงในการล็อกช่วยลดความขัดแย้งส่วนใหญ่ก่อนที่จะเกิดขึ้น โมเดลการแตกสาขาของ Apidog ช่วยลดความขัดแย้งในการแก้ไขพร้อมกันโดยธรรมชาติของการออกแบบ
บทนำ
คุณสมบัติการแก้ไขร่วมกันของ SwaggerHub มีประโยชน์อย่างแท้จริง สมาชิกทีมหลายคนสามารถทำงานบนคำจำกัดความ API เดียวกันได้ การเปลี่ยนแปลงสามารถมองเห็นได้แบบเรียลไทม์ และการผสานรวม Git ช่วยให้ทีมสามารถรักษาข้อมูลจำเพาะให้ซิงโครไนซ์กับคลังโค้ดต้นทางได้
แต่การทำงานร่วมกันนำมาซึ่งความขัดแย้ง วิศวกรสองคนแก้ไขเอนด์พอยต์เดียวกันพร้อมกัน ข้อมูลจำเพาะได้รับการอัปเดตใน SwaggerHub และแยกต่างหากใน GitHub และกระบวนการซิงค์พบกับเวอร์ชันที่แตกต่างกัน โดเมนได้รับการอัปเดตในขณะที่ API อยู่ระหว่างการตรวจสอบ ความขัดแย้งเหล่านี้สามารถจัดการได้ แต่จะสร้างความรบกวนเมื่อเกิดขึ้นโดยไม่คาดคิด และทีมไม่มีกระบวนการแก้ไขที่ชัดเจน
คู่มือนี้อธิบายประเภทของความขัดแย้งที่เกิดขึ้นใน SwaggerHub วิธีแก้ไขแต่ละประเภท และวิธีป้องกันด้วยวินัยการทำงานที่ดีขึ้น ส่วนสุดท้ายจะกล่าวถึงวิธีที่ Apidog จัดการกับปัญหาประเภทเดียวกัน
ประเภทของความขัดแย้งในการซิงค์ใน SwaggerHub
1. ความขัดแย้งในการแก้ไขพร้อมกัน SwaggerHub อนุญาตให้ผู้ใช้หลายคนแก้ไขคำจำกัดความ API ได้พร้อมกัน เมื่อผู้ใช้สองคนแก้ไขส่วนเดียวกันของข้อมูลจำเพาะพร้อมกัน การบันทึกครั้งสุดท้ายจะเป็นผู้ชนะ ไม่มีการรวม — การบันทึกครั้งที่สองจะเขียนทับการเปลี่ยนแปลงของผู้ใช้คนแรก ทางเทคนิคแล้วนี่ไม่ใช่ "ความขัดแย้ง" ในความหมายของ Git (ไม่มีสถานะข้อผิดพลาด) แต่ทำให้ข้อมูลสูญหายได้หากทีมไม่ระมัดระวัง
2. ความขัดแย้งในการซิงค์ระหว่าง SwaggerHub กับ Git SwaggerHub ทำงานร่วมกับ GitHub, GitLab และ Bitbucket เมื่อข้อมูลจำเพาะถูกบันทึกใน SwaggerHub มันสามารถพุชไปยังคลังที่กำหนดค่าไว้ได้โดยอัตโนมัติ เมื่อไฟล์ข้อมูลจำเพาะถูกคอมมิตโดยตรงไปยังคลัง มันสามารถซิงค์กลับไปยัง SwaggerHub ได้ หากทั้งสองอย่างเกิดขึ้นอย่างอิสระ คุณจะได้รับเวอร์ชันที่ขัดแย้งกันซึ่งกระบวนการซิงค์ของ SwaggerHub ไม่สามารถประนีประนอมได้โดยอัตโนมัติ
3. ความขัดแย้งในการแยกเวอร์ชัน API (API version fork conflicts) เมื่อคุณแยกเวอร์ชัน API ใน SwaggerHub เพื่อสร้างสาขาการทำงานใหม่ แล้วพยายามรวมการเปลี่ยนแปลงกลับ ความแตกต่างระหว่างสาขาที่แยกออกมากับต้นฉบับสามารถสร้างความขัดแย้งที่ต้องแก้ไขด้วยตนเองได้
4. ความขัดแย้งในการไม่ตรงกันของเวอร์ชันโดเมน (Domain version mismatch conflicts) หาก API อ้างอิงถึง SwaggerHub Domain ในเวอร์ชันที่กำหนด และเวอร์ชันโดเมนนั้นถูกเลิกใช้งานหรือถูกแก้ไขโดยไม่เข้ากัน API ที่อ้างอิงอาจพบข้อผิดพลาดในการแก้ไข นี่ไม่ใช่ความขัดแย้งในการซิงค์โดยตรง แต่ทำให้เกิดการหยุดชะงักที่คล้ายกันและต้องการขั้นตอนการแก้ไขที่คล้ายกัน
5. ความขัดแย้งในการดึง Git ในคลังที่เชื่อมต่อ (Git pull conflicts in connected repositories) เมื่อคลัง Git ที่เชื่อมต่อกับ SwaggerHub มีสาขาหรือการรวมที่ส่งผลให้เกิดความขัดแย้งในไฟล์ข้อมูลจำเพาะ กระบวนการซิงค์ของ SwaggerHub จะแสดงความขัดแย้งเหล่านั้นเมื่อซิงค์ครั้งต่อไป
การแก้ไขความขัดแย้งในการแก้ไขพร้อมกัน
"ความขัดแย้ง" ประเภทนี้เป็นสิ่งที่พบบ่อยที่สุดและมองไม่เห็นมากที่สุด ไม่มีข้อความแสดงข้อผิดพลาด — การเปลี่ยนแปลงของผู้ใช้คนหนึ่งจะหายไปเฉยๆ
การแก้ไข:
- หากคุณสังเกตเห็นว่ามีการเปลี่ยนแปลงหายไปหลังจากสมาชิกทีมคนอื่นบันทึก ให้ตรวจสอบประวัติการเปลี่ยนแปลงของ SwaggerHub (หากมีในแผนของคุณ) เพื่อดูว่ามีอะไรถูกเขียนทับไปบ้าง
- ขอให้สมาชิกทีมที่บันทึกครั้งสุดท้ายเปรียบเทียบสถานะข้อมูลจำเพาะปัจจุบันกับสำเนาในเครื่องของพวกเขา
- ป้อนการเปลี่ยนแปลงที่ขาดหายไปใหม่ด้วยตนเอง
การป้องกันคือทางออกที่แท้จริงเพียงอย่างเดียว ดูส่วนการป้องกันด้านล่าง
การแก้ไขความขัดแย้งในการซิงค์ระหว่าง SwaggerHub กับ Git
เมื่อ SwaggerHub และคลัง Git ของคุณแตกต่างกันไป คุณมักจะเห็นข้อผิดพลาดในการซิงค์ในแผงการผสานรวม Git ของ SwaggerHub ซึ่งระบุว่าไม่สามารถพุชอัตโนมัติได้เนื่องจากรีโมตมีการเปลี่ยนแปลงที่ไม่ได้อยู่ในเวอร์ชันของ SwaggerHub
ขั้นตอนการแก้ไข:
ขั้นตอนที่ 1: ดึงข้อมูลจำเพาะปัจจุบันจากคลัง Git ของคุณ ดาวน์โหลดไฟล์ YAML หรือ JSON จากสาขาที่ก่อให้เกิดความขัดแย้ง
ขั้นตอนที่ 2: ดึงข้อมูลจำเพาะปัจจุบันจาก SwaggerHub ส่งออก API เป็น YAML จาก SwaggerHub
ขั้นตอนที่ 3: เปรียบเทียบสองไฟล์ ใช้เครื่องมือเปรียบเทียบใดๆ (เช่น diff, การดูความแตกต่างของ VS Code หรือเครื่องมือเปรียบเทียบที่รู้จัก OpenAPI) ระบุว่ามีการเปลี่ยนแปลงใดบ้างใน Git ที่ไม่มีใน SwaggerHub และในทางกลับกัน
ขั้นตอนที่ 4: รวมด้วยตนเอง สร้างเวอร์ชันข้อมูลจำเพาะที่ประนีประนอมซึ่งรวมการเปลี่ยนแปลงทั้งสองชุด สิ่งนี้ต้องใช้การตัดสินของมนุษย์ — เครื่องมือรวมอัตโนมัติอาจสร้าง YAML ที่ถูกต้องตามหลักไวยากรณ์แต่ผิดความหมาย
ขั้นตอนที่ 5: เลือกแหล่งข้อมูลที่น่าเชื่อถือเพียงแหล่งเดียว ตัดสินใจว่า SwaggerHub หรือ Git เป็นแหล่งข้อมูลที่มีอำนาจ แล้วอัปเดตอีกฝ่ายหนึ่ง หาก Git เป็นแหล่งข้อมูลที่มีอำนาจ ให้คอมมิตข้อมูลจำเพาะที่รวมแล้วไปยังคลัง และให้การซิงค์ดึงข้อมูลนั้นเข้าสู่ SwaggerHub หาก SwaggerHub เป็นแหล่งข้อมูลที่มีอำนาจ ให้พุชข้อมูลจำเพาะที่รวมแล้วจาก SwaggerHub ไปยัง Git
ขั้นตอนที่ 6: ตรวจสอบการซิงค์ หลังจากการอัปเดต ให้ยืนยันว่าแผงการผสานรวม Git ของ SwaggerHub แสดงสถานะการซิงค์ที่สะอาดปราศจากความขัดแย้ง
เครื่องมือที่เป็นประโยชน์: openapi-diff เครื่องมือเปรียบเทียบ OpenAPI หลายตัวจะเปรียบเทียบเวอร์ชันข้อมูลจำเพาะในระดับเชิงความหมาย (การเพิ่มเอนด์พอยต์ การเปลี่ยนแปลงฟิลด์ การเปลี่ยนแปลงแบบ breaking เทียบกับการเปลี่ยนแปลงแบบ non-breaking) แทนที่จะเป็นแบบบรรทัดต่อบรรทัด เครื่องมืออย่าง oasdiff หรือ openapi-diff ให้ผลลัพธ์ที่ชัดเจนกว่าการเปรียบเทียบ YAML ดิบ
การแก้ไขความขัดแย้งในการไม่ตรงกันของเวอร์ชันโดเมน
หาก API ของคุณอ้างอิงถึงเวอร์ชันโดเมนที่มีการเปลี่ยนแปลงหรือถูกเลิกใช้งานไปแล้ว:
ขั้นตอนที่ 1: ระบุว่า API ของคุณอ้างอิงถึงเวอร์ชันโดเมนใด ดูที่ URL $ref ในข้อมูลจำเพาะของคุณ — ซึ่งจะรวมหมายเลขเวอร์ชันไว้ด้วย
ขั้นตอนที่ 2: ตรวจสอบบันทึกการเปลี่ยนแปลงสำหรับเวอร์ชันโดเมน ตรวจสอบว่ามีอะไรเปลี่ยนแปลงไประหว่างเวอร์ชันที่คุณปักหมุดไว้ปัจจุบันกับเวอร์ชันล่าสุด
ขั้นตอนที่ 3: ประเมินว่าการเปลี่ยนแปลงนั้นเป็นแบบ breaking change หรือไม่ การเพิ่มฟิลด์เสริมใหม่ไม่ใช่ breaking change การลบฟิลด์ การเปลี่ยนประเภท หรือการเปลี่ยนชื่อคุณสมบัติเป็น breaking change
ขั้นตอนที่ 4: อัปเดตเส้นทาง $ref ของ API ของคุณเพื่ออ้างอิงเวอร์ชันโดเมนใหม่ หากคุณตัดสินใจที่จะย้ายข้อมูล ทดสอบว่าข้อมูลจำเพาะยังคงตรวจสอบความถูกต้องได้อย่างถูกต้องหลังการอัปเดต
ขั้นตอนที่ 5: แจ้งทีม หากการเปลี่ยนแปลงโดเมนมีผลต่อ API หลายตัว ให้ประสานงานการย้ายข้อมูลเพื่อให้ทุกทีมอัปเดตตามกำหนดเวลาเดียวกัน
การแก้ไขความขัดแย้งในการแยกเวอร์ชัน API
เมื่อรวมเวอร์ชัน API ที่แยกออกมากลับเข้าสู่เวอร์ชันหลัก:
ขั้นตอนที่ 1: ส่งออกทั้งสาขาที่แยกออกมาและเวอร์ชันหลักเป็นไฟล์ YAML
ขั้นตอนที่ 2: เปรียบเทียบข้อมูลจำเพาะทั้งสองโดยใช้เครื่องมือเปรียบเทียบ OpenAPI
ขั้นตอนที่ 3: ในตัวแก้ไข SwaggerHub ให้ใช้การเปลี่ยนแปลงจากสาขาที่แยกออกมาเข้าสู่เวอร์ชันหลักด้วยตนเอง (หรือในทางกลับกัน ขึ้นอยู่กับว่าอันไหนคือสถานะสุดท้ายที่ต้องการ)
ขั้นตอนที่ 4: ตรวจสอบข้อมูลจำเพาะที่รวมแล้วในตัวแก้ไขของ SwaggerHub เพื่อยืนยันว่าไม่มีข้อผิดพลาดในการตรวจสอบความถูกต้อง
ขั้นตอนที่ 5: ลบหรือเก็บถาวรสาขาที่แยกออกมาหากไม่จำเป็นอีกต่อไป
การป้องกัน: ลดความขัดแย้งก่อนที่จะเกิดขึ้น
กำหนดโซนความเป็นเจ้าของที่ชัดเจน กำหนดส่วนต่างๆ ของข้อมูลจำเพาะ API ขนาดใหญ่ให้กับสมาชิกทีมที่แตกต่างกัน คนหนึ่งเป็นเจ้าของเอนด์พอยต์การยืนยันตัวตน อีกคนเป็นเจ้าของเอนด์พอยต์ทรัพยากร โซนการแก้ไขที่ทับซ้อนกันคือที่ที่ความขัดแย้งพร้อมกันเกิดขึ้น
ใช้การแยกสาขา (forking) สำหรับการเปลี่ยนแปลงที่ไม่เล็กน้อย สำหรับการเปลี่ยนแปลงใดๆ ที่จะใช้เวลามากกว่าหนึ่งชั่วโมงหรือต้องมีการตรวจสอบ ให้แยกเวอร์ชัน API ก่อนทำการแก้ไข สิ่งนี้จะแยกงานของคุณออกจากเวอร์ชันหลักจนกว่าคุณจะพร้อมที่จะรวม
สร้างโปรโตคอลการซิงค์ Git หากคุณใช้การผสานรวม Git ให้ตัดสินใจและบันทึกว่าทิศทางใดเป็นแหล่งข้อมูลที่เชื่อถือได้ "SwaggerHub เป็นตัวแก้ไข; Git เป็นบันทึก" หรือ "Git เป็นแหล่งความจริง; SwaggerHub ซิงค์จากมัน" — ไม่ใช่ทั้งสองอย่างพร้อมกันด้วยการแก้ไขอิสระในแต่ละด้าน
สื่อสารก่อนแก้ไขพื้นที่ที่ใช้ร่วมกัน ใช้ Slack, ระบบตั๋ว, หรือคุณสมบัติความคิดเห็นของ SwaggerHub เองเพื่อส่งสัญญาณเมื่อคุณกำลังจะแก้ไขส่วนที่ผู้อื่นอาจต้องแก้ไขด้วย การสื่อสารแบบอะซิงโครนัสช่วยป้องกันการเขียนทับการแก้ไขพร้อมกันส่วนใหญ่
ปักหมุดการอ้างอิงโดเมนอย่างชัดเจน อ้างอิงเวอร์ชันโดเมนที่เฉพาะเจาะจงเสมอในเส้นทาง $ref ของคุณ ไม่ใช่อ้างอิง "ล่าสุด" แบบลอยๆ สิ่งนี้ช่วยป้องกันการเปลี่ยนแปลงที่ทำให้เกิดการหยุดชะงักโดยอัตโนมัติจากการไหลเข้าสู่ API ของคุณโดยไม่มีการดำเนินการโดยเจตนา
ตั้งค่าการพุชอัตโนมัติอย่างระมัดระวัง การพุชอัตโนมัติเมื่อบันทึกของ SwaggerHub อาจสะดวก แต่สร้างความเสี่ยงต่อความขัดแย้งหากสมาชิกทีมคอมมิตการเปลี่ยนแปลงข้อมูลจำเพาะโดยตรงในคลัง Git ด้วย ปิดใช้งานการพุชอัตโนมัติหากคุณมีนักพัฒนาที่ทำการเปลี่ยนแปลงข้อมูลจำเพาะในทั้งสองที่
Apidog จัดการกับปัญหาเดียวกันอย่างไร
โมเดลการทำงานร่วมกันของ Apidog สร้างขึ้นจากแนวคิดการแตกสาขาแบบ Git ซึ่งช่วยป้องกันรูปแบบความขัดแย้งส่วนใหญ่เหล่านี้โดยธรรมชาติของการออกแบบ
ไม่มีการเขียนทับพร้อมกัน ใน Apidog สมาชิกทีมจะทำงานบนสาขาที่แยกจากกัน วิศวกรที่สร้างเอนด์พอยต์ใหม่จะสร้างสาขา ทำงาน และเปิดคำขอตรวจสอบเมื่อเสร็จสิ้น วิศวกรอีกคนหนึ่งที่ทำการเปลี่ยนแปลงที่แตกต่างกันก็ทำเช่นเดียวกันบนสาขาที่แยกต่างหาก การเปลี่ยนแปลงจะไม่ถูกรวมเข้ากับสาขาหลักจนกว่าจะได้รับการตรวจสอบและอนุมัติ สิ่งนี้ช่วยขจัดปัญหาการเขียนทับแบบ "การบันทึกครั้งสุดท้ายเป็นผู้ชนะ" ได้อย่างสมบูรณ์
ประตูการตรวจสอบในตัว ขั้นตอนการทำงานของการตรวจสอบและการอนุมัติหมายความว่าการเปลี่ยนแปลงข้อมูลจำเพาะจะผ่านขั้นตอนการตรวจสอบที่ชัดเจนก่อนที่จะส่งผลกระทบต่อสาขาหลักหรือเอกสารที่ทีมปลายน้ำกำลังใช้
การตรวจจับความขัดแย้งเมื่อรวม เมื่อสองสาขาแก้ไขเอนด์พอยต์หรือสคีมาเดียวกัน กระบวนการรวมของ Apidog จะแสดงความขัดแย้งออกมาอย่างชัดเจน ทีมจะแก้ไขปัญหานี้โดยเห็นภาพการเปลี่ยนแปลงทั้งสองชุดอย่างชัดเจน
เวิร์กโฟลว์แบบ Local-first สำหรับทีมที่กังวลเกี่ยวกับความขัดแย้งในการซิงค์กับคลัง Git ภายนอก เวิร์กโฟลว์ภายในเครื่องของ Apidog ช่วยลดผลกระทบ — การเปลี่ยนแปลงจะถูกตรวจสอบความถูกต้องในแพลตฟอร์มก่อนที่จะคอมมิตไปยัง Git
คำถามที่พบบ่อย
มี UI สำหรับการแก้ไขความขัดแย้งในตัวใน SwaggerHub หรือไม่? SwaggerHub ไม่มีอินเทอร์เฟซการแก้ไขความขัดแย้งในการรวมแบบกราฟิกเหมือนเครื่องมือ Git GUI บางตัว การแก้ไขความขัดแย้งต้องทำด้วยตนเอง — ดาวน์โหลดทั้งสองเวอร์ชัน เปรียบเทียบความแตกต่างภายนอก SwaggerHub แล้วอัปโหลดเวอร์ชันที่แก้ไขแล้ว
เครื่องมือเปรียบเทียบ OpenAPI ที่ดีที่สุดสำหรับใช้ระหว่างการแก้ไขความขัดแย้งคืออะไร? oasdiff เป็นเครื่องมือบรรทัดคำสั่งที่ได้รับการดูแลอย่างดี ซึ่งสร้างความแตกต่างที่มีโครงสร้างของข้อมูลจำเพาะ OpenAPI โดยแยกการเปลี่ยนแปลงที่ทำให้เกิดข้อผิดพลาดออกจากส่วนเพิ่มเติมที่ไม่ทำให้เกิดข้อผิดพลาด มันเป็นผลลัพธ์ที่มีประโยชน์มากกว่าการเปรียบเทียบ YAML ดิบสำหรับงานข้อมูลจำเพาะ API
ฉันสามารถล็อก API ใน SwaggerHub เพื่อป้องกันไม่ให้ผู้อื่นแก้ไขได้หรือไม่? SwaggerHub ไม่มีกลไกการล็อกไฟล์ในตัว วิธีแก้ไขที่ใกล้เคียงที่สุดคือการใช้ระบบบทบาทของ SwaggerHub เพื่อจำกัดสิทธิ์การแก้ไขชั่วคราวในขณะที่คุณทำการเปลี่ยนแปลง จากนั้นจึงกู้คืนสิทธิ์
ฉันจะรู้ได้อย่างไรว่าเวอร์ชันใดของ API ที่ขัดแย้งกันนั้นถูกต้อง? ตรวจสอบบันทึกกิจกรรมของ SwaggerHub (หากแผนของคุณรวมอยู่ด้วย) เพื่อดูว่าใครทำการเปลี่ยนแปลงอะไรและเมื่อใด หากคุณใช้ Git ประวัติการคอมมิตเป็นบันทึกที่เชื่อถือได้ หากทั้งสองอย่างไม่สามารถสรุปได้ ให้ปรึกษาสมาชิกทีมที่เกี่ยวข้องเพื่อสร้างเจตนาขึ้นมาใหม่
SwaggerHub จะแจ้งเตือนฉันเมื่อโดเมนที่ฉันใช้งานอยู่ได้รับการอัปเดตหรือไม่? SwaggerHub สามารถแจ้งเตือนคุณเกี่ยวกับการอัปเดตโดเมนผ่านระบบการแจ้งเตือนของมัน การที่คุณได้ตั้งค่านี้หรือไม่ขึ้นอยู่กับการตั้งค่าการแจ้งเตือนของคุณ ตรวจสอบ การตั้งค่าองค์กร > การแจ้งเตือน เพื่อกำหนดค่าการแจ้งเตือนสำหรับการเปลี่ยนแปลงโดเมน
การย้ายไปใช้ Apidog ป้องกันความขัดแย้งในการซิงค์ทั้งหมดหรือไม่? การแตกสาขาช่วยลดความถี่ของความขัดแย้งได้อย่างมาก แต่ไม่สามารถขจัดออกไปได้ทั้งหมด สองสาขาที่แก้ไขเอนด์พอยต์เดียวกันยังคงต้องได้รับการประนีประนอมเมื่อรวมกัน สิ่งที่การแตกสาขาทำคือทำให้ความขัดแย้งเหล่านั้นปรากฏและชัดเจน แทนที่จะเป็นการเขียนทับแบบเงียบๆ
ความขัดแย้งในการซิงค์ใน SwaggerHub ส่วนใหญ่เป็นปัญหาเกี่ยวกับขั้นตอนการทำงาน ไม่ใช่ปัญหาของผลิตภัณฑ์ การกำหนดความเป็นเจ้าของที่ชัดเจน วินัยในการจัดการสาขา (branch discipline) และโปรโตคอลการซิงค์ Git ที่กำหนดไว้อย่างชัดเจนจะช่วยป้องกันปัญหาส่วนใหญ่ก่อนที่จะเกิดขึ้น เมื่อเกิดความขัดแย้งขึ้น กระบวนการที่เป็นระบบ — ส่งออกทั้งสองเวอร์ชัน เปรียบเทียบความแตกต่างด้วยเครื่องมือที่เหมาะสม รวมด้วยตนเอง ตรวจสอบความถูกต้อง และยืนยันการซิงค์ — จะแก้ไขปัญหาเหล่านั้นได้อย่างน่าเชื่อถือ โมเดลการแตกสาขาของ Apidog ช่วยลดความถี่ของความขัดแย้งโดยทำให้การทำงานพร้อมกันเป็นไปอย่างชัดเจน แต่เครื่องมือแก้ไขร่วมกันใดๆ ก็ตามจะได้รับประโยชน์จากวินัยพื้นฐานเดียวกัน