วิธีเชื่อมต่อ Apidog กับ GitHub และ GitLab

หาก API spec ของคุณอยู่ใน Apidog แต่แหล่งข้อมูลที่ถูกต้อง (source of truth) ของคุณอยู่ใน Git คุณย่อมต้องการให้ทั้งสองส่วนสอดคล้องกัน การผสานรวม Apidog Git ช่วยเชื่อมช่องว่างนี้ได้ ช่วยให้คุณสามารถเชื่อมต่อ repository ของ GitHub, GitLab หรือ Azure DevOps เข้ากับโปรเจกต์ของคุณ พุช OpenAPI spec ของคุณไปยังระบบควบคุมเวอร์ชัน (version control) และดึงการเปลี่ยนแปลงจาก repo กลับมายัง Apidog คุณจะได้รับบันทึกการตรวจสอบที่ชัดเจน (clean audit trail) การตรวจสอบโค้ด (code-review) สำหรับการเปลี่ยนแปลง spec และการสำรองข้อมูล (backup) ที่จะยังคงอยู่แม้จะเกิดอะไรขึ้นภายในแอป

นี่คือข้อมูลอ้างอิงแบบกว้างๆ ที่ครอบคลุมผู้ให้บริการทุกรายที่ Apidog รองรับ ทั้งสองวิธีที่ผลิตภัณฑ์สื่อสารกับ Git และการตัดสินใจเชิงปฏิบัติที่คุณจะต้องเผชิญ: repository ใด, branch ใด, ใครสามารถพุชได้ และจะทำอย่างไรเมื่อมีข้อผิดพลาดเกิดขึ้น หากคุณต้องการเพียงแค่คำแนะนำที่เน้น GitHub โดยเฉพาะ โปรดอ่านคู่มือเฉพาะเกี่ยวกับวิธี ซิงค์ OpenAPI spec ของคุณไปยัง GitHub ในที่นี้ เราจะกล่าวถึงในวงกว้างกว่า

Apidog Git integration ทำอะไรได้บ้าง

Apidog สื่อสารกับ Git ได้สองวิธีที่แตกต่างกัน ซึ่งแต่ละวิธีช่วยแก้ปัญหาที่ต่างกัน และคุณสามารถเลือกใช้วิธีใดวิธีหนึ่ง หรือทั้งสองวิธีก็ได้ การสับสนระหว่างสองวิธีนี้เป็นสาเหตุที่พบบ่อยที่สุดของความเข้าใจผิด ดังนั้นเรามาแยกแยะกันก่อน

ความสามารถแรกคือการซิงค์แบบสองทิศทางผ่าน Spec-First Mode คุณสามารถแก้ไขเอกสาร OpenAPI ของคุณในรูปแบบ YAML หรือ JSON ภายในตัวแก้ไขสไตล์ IDE ของ Apidog คอมมิตการเปลี่ยนแปลงของคุณ และพุชไปยัง branch ที่เชื่อมต่ออยู่ เมื่อมีผู้อื่นอัปเดต spec ใน repo คุณสามารถดึงการเปลี่ยนแปลงเหล่านั้นกลับมายัง Apidog ได้ นี่คือการเดินทางไปกลับที่แท้จริง: การแก้ไขไหลออกไปยัง Git และการเปลี่ยนแปลงจาก repo ก็ไหลกลับเข้ามา

ความสามารถที่สองคือการสำรองข้อมูล API spec อัตโนมัติไปยัง Git ในส่วนนี้ Apidog จะส่งออกไฟล์ OpenAPI/Swagger ของแต่ละโมดูลและพุชไปยัง repository ตามกำหนดเวลา นี่เป็นกระบวนการแบบทางเดียวและไม่ต้องดูแล คุณเพียงตั้งค่าครั้งเดียว ระบบก็จะเก็บสำเนา spec ของคุณที่มีเวอร์ชันไว้ใน Git โดยที่คุณไม่ต้องทำอะไรเลย มันคือตาข่ายนิรภัย ไม่ใช่ขั้นตอนการทำงานสำหรับการแก้ไข

โปรดจำความแตกต่างนี้ไว้ตลอดบทความที่เหลือ เมื่อเราพูดว่า “ซิงค์” เราหมายถึงกระบวนการ Spec-First Mode แบบสองทิศทาง เมื่อเราพูดว่า “สำรองข้อมูล” เราหมายถึงการส่งออกตามกำหนดเวลาแบบทางเดียว

ผู้ให้บริการ Git ที่รองรับ

Apidog รองรับผู้ให้บริการหลักสามรายที่ทีมส่วนใหญ่ใช้งานอยู่แล้ว GitHub และ GitLab เชื่อมต่อโดยตรงผ่านกระบวนการอนุญาต (authorization) ดั้งเดิมของตนเอง ส่วน Azure DevOps เชื่อมต่อผ่าน Generic Git Connection ซึ่งทำงานได้กับโฮสต์ Git ใดๆ ที่รองรับการรับรองความถูกต้องด้วย HTTPS มาตรฐาน

Generic Git Connection เป็นช่องทางสำรอง หากโฮสต์ของคุณไม่ใช่ GitHub หรือ GitLab โดยตรง แต่รองรับ Git มาตรฐานผ่าน HTTPS ด้วยการยืนยันตัวตนด้วยโทเค็น การเชื่อมต่อแบบ Generic ก็มักจะรองรับได้ Azure DevOps เป็นกรณีตัวอย่างหลัก แต่เส้นทางเดียวกันนี้ก็ครอบคลุมการตั้งค่าแบบ self-hosted ที่มีการเปิดเผย HTTPS clone URL

การเชื่อมต่อผู้ให้บริการ Git ของคุณ

ขั้นตอนการเชื่อมต่อคือจุดที่คุณให้สิทธิ์ Apidog ในการเข้าถึงที่จำเป็นสำหรับการอ่านและเขียน repo ของคุณ กลไกอาจแตกต่างกันเล็กน้อยตามผู้ให้บริการ แต่รูปแบบจะคล้ายกัน: อนุมัติสิทธิ์, เลือก repo, เลือก branch

สำหรับ GitHub คุณจะให้สิทธิ์ผ่านหน้าจอ OAuth ของ GitHub Apidog จะร้องขอสิทธิ์เข้าถึง repository เพื่อให้สามารถอ่าน spec และพุชคอมมิตได้ หาก repo เป็นขององค์กร GitHub อาจส่งคำขอผ่านผู้ดูแลระบบองค์กรเพื่ออนุมัติการเข้าถึงของบุคคลที่สาม repo ส่วนบุคคลจะได้รับการอนุมัติทันทีภายใต้บัญชีของคุณเอง

สำหรับ GitLab กระบวนการจะคล้ายกับ GitHub คุณจะล็อกอินผ่านหน้าจอ OAuth ของ GitLab และให้สิทธิ์เข้าถึง repository GitLab ที่จัดการด้วยตนเอง (self-managed) สามารถทำงานได้ตราบใดที่ Apidog สามารถเข้าถึงอินสแตนซ์นั้นผ่านเครือข่ายได้

สำหรับ Azure DevOps คุณจะใช้ Generic Git Connection แทนการทำ OAuth handshake คุณจะต้องระบุ HTTPS clone URL ของ repository และโทเค็นการเข้าถึงส่วนบุคคล (PAT) สร้าง PAT ใน Azure DevOps โดยให้สิทธิ์ในการอ่านและเขียนโค้ด จากนั้นนำไปวางใน Apidog โทเค็นนี้คือข้อมูลรับรองที่อนุญาตให้ Apidog พุชคอมมิต ดังนั้นควรกำหนดขอบเขตให้เข้าถึงเฉพาะ repo ที่จำเป็นเท่านั้น

• Repo องค์กรเทียบกับ repo ส่วนบุคคล โดยทั่วไปแล้ว repository ขององค์กรมักจะต้องให้ผู้ดูแลระบบอนุมัติการผสานรวมเพียงครั้งเดียว หากการอนุญาตของคุณดูเหมือนจะสำเร็จ แต่ Apidog ไม่สามารถเห็น repo ได้ โดยปกติแล้วหมายถึงการอนุมัติจากผู้ดูแลระบบยังขาดหายไป
• กำหนดขอบเขตโทเค็นอย่างจำกัด สำหรับ Azure DevOps และการเชื่อมต่อแบบ Generic ใดๆ ให้สิทธิ์ PAT ในการอ่าน/เขียนโค้ดสำหรับโปรเจกต์เป้าหมายเท่านั้น หลีกเลี่ยงโทเค็นที่มีสิทธิ์เข้าถึงบัญชีทั้งหมด
• Repo ส่วนตัวก็ใช้งานได้ Apidog สามารถทำงานกับ repository ส่วนตัวได้ การเข้าถึงมาจากสิทธิ์อนุญาตหรือโทเค็นที่คุณให้ไว้ ไม่ใช่จากสถานะการมองเห็นแบบสาธารณะ

เมื่อเชื่อมต่อผู้ให้บริการแล้ว คุณจะสร้างโปรเจกต์ Apidog จาก repository และ branch โดยทั่วไปคือ main การจับคู่นั้นคือสิ่งที่เชื่อมโยง spec ของคุณเข้ากับตำแหน่งเฉพาะในระบบควบคุมเวอร์ชัน หากคุณยังใหม่กับแนวทางปฏิบัติที่กว้างขึ้นนี้ คู่มือของเราเรื่อง การควบคุมเวอร์ชัน OpenAPI ด้วย Git จะครอบคลุมแนวทางปฏิบัติที่ควรนำไปใช้ก่อนที่คุณจะตั้งค่าทุกอย่าง

การซิงค์แบบสองทิศทางด้วย Spec-First Mode

Spec-First Mode คือที่อยู่ของการซิงค์แบบสองทิศทาง มันเปลี่ยน Apidog ให้เป็นตัวแก้ไข spec ที่คอมมิตไปยัง Git ได้เหมือนโค้ดทั่วไป คุณสามารถอ่านข้อมูลอ้างอิงฉบับเต็มได้ใน เอกสารอย่างเป็นทางการของ Apidog นี่คือวิธีการทำงานของกระบวนการแบบไปกลับในการใช้งานจริง

คุณแก้ไขเอกสาร OpenAPI โดยตรงในรูปแบบ YAML หรือ JSON ตัวแก้ไขเป็นสไตล์ IDE: ให้คุณไฮไลต์ไวยากรณ์ ตรวจสอบความถูกต้องแบบเรียลไทม์ และเติมข้อความอัตโนมัติ ดังนั้น $ref ที่ผิดรูปแบบหรือฟิลด์ที่จำเป็นขาดหายไปจะปรากฏขึ้นในขณะที่คุณพิมพ์ แทนที่จะเป็นหลังจากที่คุณพุช ขณะที่คุณแก้ไข แถบด้านซ้ายจะแยกวิเคราะห์เอกสารโดยอัตโนมัติเป็นโครงร่าง, เส้นทาง, การดำเนินการ และ schemas เพื่อให้คุณสามารถนำทาง spec ขนาดใหญ่ได้โดยไม่ต้องเลื่อนดูข้อความดิบ

การแก้ไขทั่วไปมีลักษณะดังนี้ สมมติว่าคุณเพิ่ม endpoint:

paths:
 /v1/orders/{orderId}:
 get:
 operationId: getOrder
 summary: Retrieve a single order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: The requested order
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/Order'

เมื่อคุณบันทึกการเปลี่ยนแปลงนั้น Apidog จะจัดเตรียมเป็นการแก้ไขในเครื่อง (local edit) จากนั้นคุณจะคอมมิตพร้อมข้อความและพุชไปยัง branch ที่เชื่อมต่ออยู่ เช่นเดียวกับที่คุณทำในเวิร์กโฟลว์ Git ทั่วไป หลังจากพุชสำเร็จ ตัวบ่งชี้การซิงค์จะแสดงว่า “Synced just now” เพื่อยืนยันว่า Apidog และ branch มีเนื้อหาเดียวกัน

ทิศทางการพูล (pull) ก็มีความสำคัญไม่แพ้กัน เมื่อเพื่อนร่วมทีมแก้ไข spec ใน repo และพุช คุณจะต้องพูลการเปลี่ยนแปลงเหล่านั้นมายัง Apidog เพื่ออัปเดตสำเนาในเครื่องของคุณให้เป็นปัจจุบัน นี่คือสิ่งที่ทำให้การผสานรวมนี้เป็นแบบสองทิศทางอย่างแท้จริง: repo ไม่ได้เป็นเพียงเป้าหมายในการสำรองข้อมูลเท่านั้น แต่ยังเป็นคู่ค้าด้วย

หากคุณทำการแก้ไขที่คุณไม่ต้องการเก็บไว้ คุณสามารถทิ้งการแก้ไขที่ยังไม่ได้พุช (discard unpushed edits) ได้ก่อนการคอมมิต ซึ่งจะคืนค่าสำเนาที่ทำงานอยู่ของคุณให้ตรงกับสถานะที่ซิงค์ครั้งล่าสุด ซึ่งสะดวกเมื่อคุณกำลังทดลองและตัดสินใจว่าการเปลี่ยนแปลงนั้นไม่คุ้มค่าที่จะเก็บไว้

จังหวะการคอมมิตและพุชนี้เป็นหัวใจสำคัญของ เวิร์กโฟลว์ API ที่เป็น Git-native การเปลี่ยนแปลง spec จะผ่านกระบวนการรีวิว ประวัติ และกลไกการย้อนกลับเช่นเดียวกับโค้ดส่วนที่เหลือของคุณ ผู้รีวิวสามารถแสดงความคิดเห็นเกี่ยวกับความแตกต่างของ YAML ใน pull request การอนุมัติจะเป็นประตูสู่การรวมเข้าด้วยกัน (merge) และประวัติการออกแบบ API ของคุณก็จะอ่านได้เหมือนประวัติโค้ดของคุณ

การสำรองข้อมูล API spec อัตโนมัติไปยัง Git

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

นี่คือกลไกการทำงาน Apidog สามารถสำรองไฟล์ OpenAPI/Swagger สำหรับแต่ละโมดูลไปยัง Git repository ได้ โดยรองรับทั้ง GitHub, GitLab และ Azure DevOps เมื่อคุณบันทึกการกำหนดค่าการสำรองข้อมูลแล้ว ระบบจะพุชไฟล์ OpenAPI Spec ของโมดูลไปยัง repo ที่ระบุโดยอัตโนมัติ การพุชจะเกิดขึ้นในช่วงเวลาที่กำหนดแบบสุ่มนอกเวลาทำการในตอนกลางคืน ซึ่งช่วยให้ไม่รบกวนเวลาทำงานของคุณและกระจายโหลด

สิ่งที่ถูกจัดเก็บคือเอกสาร OpenAPI/Swagger ที่ส่งออกสำหรับโมดูลนั้น ซึ่งเป็นสแนปช็อตของสัญญา API ณ ปัจจุบัน เนื่องจากทุกการพุชคือหนึ่งคอมมิต คุณจึงสามารถสะสมประวัติเวอร์ชันใน Git ได้ คุณสามารถเปรียบเทียบสัญญาของสัปดาห์ที่แล้วกับวันนี้ ดูว่าฟิลด์ใดเปลี่ยนแปลงไปเมื่อใด และกู้คืนเวอร์ชันก่อนหน้าได้โดยตรงจาก repo หากจำเป็น

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

การเลือกโครงสร้าง branch และ repo

การตัดสินใจเชิงโครงสร้างที่คุณทำล่วงหน้าจะส่งผลต่อความราบรื่นของการผสานรวมในภายหลัง มีคำถามหลักสองข้อ: branch ใด และจำนวน repo เท่าใด

การเลือก branch ทีมส่วนใหญ่ซิงค์ไปยัง main สำหรับ canonical spec และใช้ feature branch สำหรับการออกแบบที่กำลังดำเนินการอยู่ การชี้ Apidog ไปยัง feature branch ช่วยให้คุณสามารถทำซ้ำการเปลี่ยนแปลง spec แยกต่างหาก เปิด pull request และรวม (merge) หลังจากผ่านการรีวิว การออกแบบ API ของคุณจะตามแบบจำลองการแตกแขนง (branching model) เช่นเดียวกับโค้ดของคุณ การชี้ Apidog ไปยัง main โดยตรงนั้นง่ายกว่า แต่จะข้ามขั้นตอนการรีวิว ดังนั้นควรใช้สำหรับทีมขนาดเล็กหรือการเปลี่ยนแปลงที่มีความเสี่ยงต่ำ

หนึ่ง repo หรือหลาย repo ไม่มีคำตอบเดียวที่ถูกต้อง แต่ข้อดีข้อเสียก็ชัดเจน:

• หนึ่ง repo ต่อหนึ่ง API ช่วยให้ประวัติของแต่ละ spec สะอาดและควบคุมการเข้าถึงได้อย่างจำกัด เหมาะสมอย่างยิ่งเมื่อทีมที่แตกต่างกันเป็นเจ้าของ API ที่แตกต่างกัน
• Monorepo สำหรับ spec ทั้งหมดจะรวมศูนย์ทุกสิ่งและทำให้การค้นหาและรีวิวข้าม API ง่ายขึ้น ทำงานได้ดีเมื่อทีมแพลตฟอร์มทีมเดียวเป็นเจ้าของ API surface เพียงแค่จัดโครงสร้างไดเรกทอรีให้คาดเดาได้ โดยมีหนึ่งโฟลเดอร์ต่อหนึ่งโมดูล เพื่อไม่ให้การสำรองข้อมูลและการซิงค์ชนกัน

หากคุณใช้ monorepo ให้แต่ละโมดูลมีเส้นทางของตนเอง ซึ่งจะช่วยให้การสำรองข้อมูลอัตโนมัติเป็นระเบียบ และทำให้การเปรียบเทียบ spec (spec diffs) อ่านง่ายในการรีวิว

สิทธิ์ของทีมและการเข้าถึง

การผสานรวม Git เกี่ยวข้องกับข้อมูลรับรอง ดังนั้นจึงควรพิจารณาอย่างรอบคอบว่าใครสามารถทำอะไรได้บ้าง สิทธิ์จะอยู่สองที่: ภายใน Apidog และภายในผู้ให้บริการ Git ของคุณ

ภายใน Apidog สิทธิ์ของทีมจะถูกกำหนดค่าระหว่างการตั้งค่าโปรเจกต์ ซึ่งเป็นจุดที่คุณตัดสินใจว่าใครสามารถซิงค์และพุชไปยัง repo ที่เชื่อมต่อได้ จำกัดสิทธิ์การพุชเฉพาะผู้ที่เป็นเจ้าของ spec และให้ผู้อื่นมีสิทธิ์อ่านเท่านั้น ซึ่งจะช่วยป้องกันการพุชโดยไม่ตั้งใจจากผู้ร่วมให้ข้อมูลที่เพียงแค่เรียกดูการออกแบบ API

ภายในผู้ให้บริการ Git ของคุณ ข้อมูลรับรองมีความสำคัญ สำหรับ GitHub และ GitLab การอนุญาต OAuth จะมีสิทธิ์การเข้าถึงของผู้ใช้ที่ให้สิทธิ์นั้น สำหรับ Azure DevOps และการเชื่อมต่อแบบ generic โทเค็นการเข้าถึงส่วนบุคคล (personal access token) คือข้อมูลรับรอง ให้ถือว่าเป็นความลับ อย่าคัดลอกโทเค็นลงในเอกสารที่แชร์ กำหนดขอบเขตให้เข้าถึงเฉพาะ repo เป้าหมายเท่านั้น และหมุนเวียน (rotate) โทเค็นตามรอบเดียวกับที่คุณหมุนเวียนความลับอื่นๆ หากมีคนออกจากทีม ให้เพิกถอนโทเค็นของพวกเขาและทำการอนุญาตใหม่ภายใต้บัญชีที่ยังใช้งานอยู่

หลักการง่ายๆ คือ: การผสานรวมจะปลอดภัยเท่ากับโทเค็นที่อ่อนแอที่สุดที่อยู่เบื้องหลังมันเท่านั้น กำหนดขอบเขตให้แคบและระบุความเป็นเจ้าของให้ชัดเจน

การจัดการข้อขัดแย้งในการรวม (merge conflicts) และความคลาดเคลื่อน (drift)

เนื่องจาก Apidog คอมมิตประวัติ Git จริงๆ จึงสืบทอดโมเดลข้อขัดแย้งของ Git และเครื่องมือของ Git สำหรับการแก้ไข ข้อขัดแย้งจะเกิดขึ้นเมื่อคนสองคนเปลี่ยนแปลงส่วนเดียวกันของ spec ก่อนที่จะซิงค์

ลองจินตนาการสถานการณ์ คุณแก้ไข Order schema ใน Apidog และพุช เพื่อนร่วมทีมแก้ไข schema เดียวกันในฝั่ง repo และพุชก่อน เมื่อคุณพยายามปรับความเข้ากัน Git จะแจ้งข้อขัดแย้งบน YAML เนื่องจากทั้งสองฝ่ายเปลี่ยนแปลงบรรทัดที่ทับซ้อนกัน นี่ไม่ใช่ปัญหาของ Apidog แต่เป็น merge conflict ปกติของ Git บนไฟล์ YAML และคุณสามารถแก้ไขได้ตามวิธีปกติ

เพื่อหลีกเลี่ยงข้อขัดแย้ง ให้พูลก่อนพุช การนำสถานะ repo ล่าสุดเข้ามาใน Apidog ก่อนคอมมิตการเปลี่ยนแปลงของคุณจะช่วยให้สำเนาที่ทำงานอยู่ของคุณเป็นปัจจุบันและลดช่วงเวลาที่การแก้ไขสองชุดจะชนกัน เมื่อเกิดข้อขัดแย้ง ให้แก้ไขบน YAML ด้วยวิธีเดียวกับที่คุณแก้ไข merge conflict ทั่วไป: เลือกบรรทัดที่ถูกต้อง รักษาเอกสารให้ถูกต้อง และซิงค์ใหม่ การตรวจสอบแบบเรียลไทม์ของตัวแก้ไขจะช่วยในส่วนนี้ การรวมที่ผิดพลาดซึ่งทำให้โครงสร้าง OpenAPI เสียหายจะปรากฏขึ้นทันที แทนที่จะปรากฏหลังจากที่คุณพุชไปแล้ว

ความคลาดเคลื่อน (drift) ที่ Apidog และ repo ค่อยๆ แตกต่างกันออกไปอย่างเงียบๆ เป็นปัญหาเดียวกันแต่เกิดขึ้นช้าๆ ตัวบ่งชี้ “Synced just now” คือสัญญาณเตือนล่วงหน้าของคุณ หากไม่แสดงว่าซิงค์ แสดงว่ามีบางอย่างยังไม่ได้พุชหรือยังไม่ได้พูล ถือเป็นสิ่งกระตุ้นให้คุณปรับให้สอดคล้องกันก่อนที่ช่องว่างจะกว้างขึ้น

การแก้ไขปัญหา

ปัญหาการผสานรวมส่วนใหญ่มีสาเหตุมาจากการยืนยันตัวตน การเลือก branch หรือการซิงค์ที่ถูกขัดจังหวะ โปรดตรวจสอบตารางก่อนที่จะสรุปว่ามีปัญหาที่ซับซ้อนกว่านั้น

หากการอนุญาตเป็นประเด็นที่เกิดขึ้นซ้ำๆ และมักจะเป็นเช่นนั้น ให้เริ่มต้นด้วยการยืนยันว่าข้อมูลรับรองยังใช้งานได้และมีขอบเขตที่ถูกต้อง โทเค็นที่ถูกเพิกถอนหรือการอนุมัติจากองค์กรที่ขาดหายไปคือสาเหตุส่วนใหญ่ของรายงานที่ว่า “มันหยุดทำงานไปเฉยๆ”

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

การซิงค์เป็นแบบทางเดียวหรือสองทิศทาง?

ขึ้นอยู่กับความสามารถที่คุณใช้งาน Spec-First Mode เป็นแบบสองทิศทาง: คุณพุชการแก้ไขไปยัง Git และพูลการเปลี่ยนแปลงจาก repo กลับมายัง Apidog ส่วนการสำรองข้อมูลอัตโนมัติเป็นแบบทางเดียว: Apidog จะส่งออก spec ของแต่ละโมดูลไปยัง repo ตามกำหนดเวลาและไม่อ่านการเปลี่ยนแปลงกลับมา

Spec ของฉันถูกเก็บไว้ที่ไหน?

ใน Git repository ที่คุณเชื่อมต่อ สำหรับ Spec-First Mode เอกสาร OpenAPI ของคุณจะอยู่ใน branch ที่คุณพุชไป สำหรับการสำรองข้อมูลอัตโนมัติ ไฟล์ OpenAPI/Swagger ที่ส่งออกของแต่ละโมดูลจะถูกคอมมิตไปยัง repo ที่คุณกำหนดค่าไว้ ในทั้งสองกรณี Git จะเก็บสำเนาที่มีเวอร์ชัน และคุณยังคงควบคุม repository ได้อย่างเต็มที่

ฉันควรซิงค์ไปยัง branch ใด?

ใช้ main สำหรับ canonical spec และใช้ feature branch สำหรับการเปลี่ยนแปลงที่กำลังดำเนินการอยู่ การซิงค์ไปยัง feature branch ช่วยให้การเปลี่ยนแปลง spec ผ่าน pull request และการรีวิวก่อนที่จะรวมเข้าด้วยกัน ซึ่งสะท้อนถึงวิธีการที่โค้ดของคุณเคลื่อนที่ผ่าน Git อยู่แล้ว

จะเกิดอะไรขึ้นหากโทเค็นของฉันถูกเพิกถอน?

การพุชจะเริ่มล้มเหลวเนื่องจาก Apidog ไม่มีสิทธิ์เขียนอีกต่อไป ทำการอนุญาตผู้ให้บริการใหม่ หรือสำหรับ Azure DevOps และการเชื่อมต่อแบบ generic ให้สร้างโทเค็นการเข้าถึงส่วนบุคคลใหม่และอัปเดตใน Apidog เมื่อข้อมูลรับรองได้รับการกู้คืนแล้ว การซิงค์และการสำรองข้อมูลจะกลับมาทำงานได้ตามปกติ

บทสรุป

การผสานรวม Apidog Git มอบเครื่องมือเสริมสองอย่าง: การซิงค์แบบสองทิศทางผ่าน Spec-First Mode สำหรับทีมที่ปฏิบัติต่อ spec เหมือนโค้ด และการสำรองข้อมูลอัตโนมัติรายโมดูลสำหรับใครก็ตามที่ต้องการเพียงตาข่ายนิรภัยที่มีเวอร์ชัน ทั้งสองอย่างทำงานร่วมกับ GitHub, GitLab และ Azure DevOps ดังนั้นคุณจึงสามารถเชื่อมต่อผู้ให้บริการที่คุณใช้อยู่แล้วแทนที่จะต้องใช้ผู้ให้บริการใหม่

เลือกความสามารถที่ตรงกับเป้าหมายของคุณ หากคุณต้องการการรีวิวและประวัติการเปลี่ยนแปลง spec ทุกครั้ง ให้ตั้งค่า Spec-First Mode และนำจังหวะการคอมมิตและพุชมาใช้ หากคุณต้องการความคงทนโดยไม่เปลี่ยนแปลงเวิร์กโฟลว์ของคุณ ให้เปิดใช้งานการสำรองข้อมูลและปล่อยให้การพุชกลางคืนจัดการเอง หลายทีมใช้งานทั้งสองอย่าง เมื่อคุณพร้อมที่จะตั้งค่า ให้เชื่อมต่อผู้ให้บริการของคุณ ชี้โปรเจกต์ไปยัง repo และ branch และปล่อยให้ API spec ของคุณอยู่ในที่ที่งานอื่นๆ ของคุณอยู่แล้ว