ซิงค์ OpenAPI Spec กับ GitHub สองวิธี

หากเอกสาร OpenAPI ของคุณอยู่ใน Git repository แต่คุณแก้ไขในไคลเอนต์ API คุณย่อมรู้ดีถึงความยุ่งยาก: คัดลอก YAML ออก, วางกลับเข้าไป, หวังว่าไม่มีใครแตะไฟล์นั้น, และภาวนาให้การนำเข้าไม่ได้ทำให้ข้อมูลบางส่วนหายไปอย่างเงียบๆ การรักษาข้อมูลจำเพาะ (spec) และ repo ให้สอดคล้องกันด้วยตนเองเป็นงานที่น่าเบื่อหน่ายซึ่งมักจะล้มเหลวเมื่อคุณกำลังรีบ

คู่มือนี้จะแสดงวิธีซิงค์ OpenAPI spec ของคุณกับ GitHub ด้วย Spec-First Mode ของ Apidog เพื่อให้ spec ใน repo และ spec ในตัวแก้ไขของคุณเป็นสิ่งเดียวกัน แทนที่จะเป็นสองสำเนาที่คุณต้องคอยจัดการ เราจะเชื่อมต่อผู้ให้บริการ, เปิดโปรเจกต์จาก repo โดยตรง, แก้ไข YAML และพุชการเปลี่ยนแปลงกลับไปยัง GitHub ในครั้งเดียว ขั้นตอนเดียวกันนี้ใช้ได้กับ GitLab

มาเริ่มกันเลย

การซิงค์สองทางหมายถึงอะไร

การซิงค์สองทางหมายถึงการแก้ไขข้อมูลสามารถไหลได้ทั้งสองทิศทางโดยอัตโนมัติ โดยไม่ต้องมีขั้นตอนการส่งออกระหว่างกลาง

• จาก Apidog ไปยัง Git: เมื่อคุณแก้ไขเอกสาร OpenAPI ใน Apidog และทำการคอมมิต การเปลี่ยนแปลงจะถูกพุชไปยัง repository ของคุณในรูปแบบ Git commit ปกติบน branch ที่คุณเลือก
• จาก Git ไปยัง Apidog: เมื่อเพื่อนร่วมทีม (หรือตัวคุณเองจาก IDE ของคุณ) พุชการเปลี่ยนแปลงไปยัง branch นั้น Apidog จะดึงกลับมาเพื่อให้ตัวแก้ไขของคุณแสดงสิ่งที่มีอยู่ใน repo จริงๆ

repository เป็นแหล่งข้อมูลที่เชื่อถือได้เพียงแหล่งเดียว (single source of truth) Apidog เป็นเครื่องมือแก้ไขที่สมบูรณ์แบบที่อยู่บนนั้น นั่นคือแนวคิดทั้งหมดเบื้องหลัง เวิร์กโฟลว์ API ที่เป็น Git-native: ข้อมูลจำเพาะจะถูกจัดการเวอร์ชัน, ตรวจสอบ, และติดตามประวัติเหมือนไฟล์อื่นๆ ใน codebase ของคุณ แทนที่จะอยู่ในเครื่องมือที่ส่งออก snapshot เป็นระยะๆ

ข้อกำหนดเบื้องต้น

ก่อนที่คุณจะเริ่ม ตรวจสอบให้แน่ใจว่าคุณมีสิ่งเหล่านี้:

• ติดตั้ง Apidog แล้ว (แอปเดสก์ท็อปหรือเว็บ) และลงชื่อเข้าใช้
• GitHub หรือ GitLab repository ที่มีเอกสาร OpenAPI อยู่แล้ว หรือคุณมีสิทธิ์เขียนถึง Azure DevOps ก็รองรับผ่าน Git Connection เช่นกัน
• เปิดใช้งาน Spec-First Mode (beta) นี่คือโหมดที่เปลี่ยนโปรเจกต์ของคุณให้เป็นเลเยอร์บางๆ เหนือ Git repo แทนที่จะเป็นที่เก็บข้อมูลของ Apidog เอง

คุณจะต้องมีสิทธิ์เขียนบน branch ที่คุณวางแผนจะซิงค์ การเข้าถึงแบบอ่านอย่างเดียวจะช่วยให้คุณดึงข้อมูลได้แต่พุชไม่ได้

ขั้นตอนที่ 1: เชื่อมต่อผู้ให้บริการ Git ของคุณ

ก่อนอื่น ให้สิทธิ์ Apidog เพื่อสื่อสารกับผู้ให้บริการของคุณ

1. เปิด Apidog และสร้างโปรเจกต์ใหม่ โดยเลือก Spec-First Mode
2. เมื่อได้รับแจ้งให้เลือกแหล่งที่มา ให้เลือกผู้ให้บริการของคุณ ได้แก่ GitHub หรือ GitLab
3. คลิก Authorize เบราว์เซอร์ของคุณจะเปิดหน้าจอ OAuth ของผู้ให้บริการ
4. ให้สิทธิ์ Apidog ในการเข้าถึง repository ที่คุณต้องการซิงค์ บน GitHub คุณสามารถกำหนดขอบเขตนี้ไปยัง repo ที่เฉพาะเจาะจง แทนที่จะเป็นบัญชีทั้งหมดของคุณ

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

สำหรับข้อมูลอ้างอิงฉบับเต็มเกี่ยวกับขั้นตอนการทำงานนี้ รวมถึง Azure DevOps ผ่าน Git Connection โปรดดูที่ เอกสาร Spec-First Mode

ขั้นตอนที่ 2: สร้างโปรเจกต์จาก repo และ branch

ตอนนี้ชี้ Apidog ไปที่ spec จริง

1. เมื่อผู้ให้บริการเชื่อมต่อแล้ว ให้เลือก repository ที่เก็บไฟล์ OpenAPI ของคุณ
2. เลือก branch ที่จะซิงค์ โดยปกติคือ main นี่คือ branch ที่ commit ของคุณจะถูกบันทึกและ branch ที่ Apidog จะคอยตรวจสอบการเปลี่ยนแปลงที่เข้ามา
3. ยืนยันพาธไปยังเอกสาร OpenAPI หาก Apidog ถาม (เช่น openapi.yaml ที่ root ของ repo หรือใต้ docs/)
4. สร้างโปรเจกต์

Apidog จะโคลน spec จาก branch นั้นและเปิดขึ้นมา แถบด้านข้างด้านซ้ายจะเต็มไปด้วย endpoint และ schema ของคุณ เนื่องจาก Apidog ได้วิเคราะห์เอกสารเป็นโครงร่างที่สามารถนำทางได้ ตอนนี้คุณกำลังดู spec ของ repo แบบสดๆ

ขั้นตอนที่ 3: แก้ไข OpenAPI YAML ของคุณในตัวแก้ไขโค้ด

Spec-First Mode ให้ตัวแก้ไขสไตล์ IDE สำหรับ OpenAPI YAML ดิบ โดยมีการเน้นไวยากรณ์, การตรวจสอบแบบอินไลน์, และการเติมข้อความอัตโนมัติ คุณเขียน OpenAPI โดยตรง; Apidog จะรักษาโครงร่างภาพให้สอดคล้องกันในขณะที่คุณพิมพ์

มาเพิ่ม endpoint เล็กๆ น้อยๆ กัน สมมติว่าคุณต้องการตรวจสอบสถานะ (health check):

paths:
 /health:
 get:
 summary: Service health check
 operationId: getHealth
 responses:
 '200':
 description: Service is up
 content:
 application/json:
 schema:
 type: object
 properties:
 status:
 type: string
 example: ok

ขณะที่คุณพิมพ์ จะมีสองสิ่งเกิดขึ้น แถบด้านข้างด้านซ้ายจะแยกวิเคราะห์โครงร่างโดยอัตโนมัติ ดังนั้นการทำงาน /health ใหม่ของคุณจะปรากฏในโครงสร้างทันที และตัวตรวจสอบจะระบุปัญหาแบบอินไลน์ เช่น บล็อก responses ที่หายไป, $ref ที่ผิดพลาด, การเยื้องที่ผิดพลาด ก่อนที่คุณจะทำการ commit หาก YAML มีรูปแบบไม่ถูกต้อง คุณจะเห็นเส้นใต้แทนที่จะไปพบในภายหลังเมื่อ pipeline ล้มเหลว

นี่คือจุดที่การควบคุมเวอร์ชันมีประโยชน์ หากคุณต้องการดูรายละเอียดเพิ่มเติมว่า diff และประวัติมีบทบาทอย่างไรกับ spec คู่มือเกี่ยวกับ การควบคุมเวอร์ชัน OpenAPI ด้วย Git จะอธิบายรายละเอียด

ขั้นตอนที่ 4: Commit และ Push

เมื่อการแก้ไขถูกต้องแล้ว ให้ส่งไปยัง GitHub

1. เปิดแผง commit (พื้นที่ Git/source-control ของโปรเจกต์)
2. ตรวจสอบการเปลี่ยนแปลง Apidog จะแสดงส่วนที่ถูกแก้ไขเมื่อเทียบกับเวอร์ชันที่ซิงค์แล้ว
3. เขียนข้อความ commit ปฏิบัติต่อเหมือน commit ทั่วไป: Add /health endpoint
4. คลิก Commit & Push

Apidog จะ commit ไปยัง branch ที่คุณเลือกและพุชไปยัง remote เปิด repository ของคุณบน GitHub แล้วคุณจะเห็น commit ในประวัติ branch ซึ่งผู้เขียนคือคุณตามที่คาดไว้ และเกี่ยวข้องกับไฟล์ OpenAPI เท่านั้น

เปลี่ยนใจก่อนที่จะพุช? คุณสามารถยกเลิกการแก้ไขที่ยังไม่ได้พุชเพื่อย้อนเอกสารกลับไปยังสถานะที่ซิงค์ล่าสุด ไม่มีอะไรออกจาก Apidog จนกว่าคุณจะ commit ดังนั้นการทดลองในเครื่องจะยังคงอยู่ในเครื่อง

ขั้นตอนที่ 5: ตรวจสอบสถานะการซิงค์

Apidog แสดงตัวบ่งชี้การซิงค์เพื่อให้คุณทราบสถานะอยู่เสมอ

หลังจากการพุชสำเร็จ ตัวบ่งชี้จะแสดงว่า "ซิงค์เมื่อสักครู่" (Synced just now) นั่นคือการยืนยันว่าตัวแก้ไขและ remote branch มีเอกสารเดียวกัน เมื่อเวลาผ่านไปก็จะอัปเดต ("ซิงค์เมื่อ 5 นาทีที่แล้ว") และเมื่อมีคนอื่นพุช Apidog จะดึงการเปลี่ยนแปลงและรีเซ็ตตัวบ่งชี้หลังจากที่มันจัดการความสอดคล้องกัน

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

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

มีบางสิ่งที่มักจะทำให้คนสับสนเป็นครั้งแรก

• การให้สิทธิ์หมดอายุหรือถูกเพิกถอน หากการพุชเริ่มล้มเหลวด้วยข้อผิดพลาดด้านสิทธิ์ ให้รันการให้สิทธิ์ใหม่จากขั้นตอนที่ 1 โทเค็นอาจถูกเพิกถอนจากฝั่งผู้ให้บริการหรือหมดอายุ
• Branch ผิดพลาด การพุชไปยัง main ที่ได้รับการป้องกันซึ่งต้องมีการร้องขอ pull request จะถูกปฏิเสธ ไม่ว่าจะซิงค์กับ branch ที่มีอยู่หรือปรับกฎการป้องกันของ branch ตรวจสอบอีกครั้งว่า branch ที่เลือกในขั้นตอนที่ 2 ตรงกับตำแหน่งที่คุณคาดว่า commit จะไปถึง
• ความขัดแย้งในการรวม (Merge conflicts) หากเพื่อนร่วมทีมพุชไปยัง branch เดียวกันในขณะที่คุณกำลังแก้ไข remote ได้เคลื่อนไปข้างหน้าสำเนาในเครื่องของคุณแล้ว ดึงข้อมูลล่าสุด, แก้ไข YAML ที่ทับซ้อนกัน, และ commit อีกครั้ง เนื่องจาก spec เป็นข้อความธรรมดา ความขัดแย้งจะได้รับการแก้ไขในลักษณะเดียวกับความขัดแย้งของโค้ดอื่นๆ
• ข้อผิดพลาดในการตรวจสอบบล็อกเวิร์กโฟลว์ของคุณ Apidog จะไม่หยุดคุณจากการ commit YAML ที่ไม่ถูกต้อง แต่คุณควรแก้ไขสิ่งที่ตัวตรวจสอบแบบอินไลน์ระบุก่อน Spec ที่สะอาดจะช่วยให้เอกสารที่สร้างขึ้น, mock, และการทดสอบของคุณถูกต้อง

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

การซิงค์กับ GitHub ใช้ได้กับ GitLab และ Azure DevOps ด้วยหรือไม่?

ใช่ Spec-First Mode รองรับ GitHub และ GitLab โดยตรง และ Azure DevOps ผ่าน Git Connection ขั้นตอนการเชื่อมต่อ-แก้ไข-commit-push เหมือนกันทั้งหมดทั้งสามแพลตฟอร์ม มีเพียงหน้าจอการให้สิทธิ์ที่แตกต่างกันไปตามผู้ให้บริการ

จะเกิดอะไรขึ้นหากเพื่อนร่วมทีมแก้ไข spec ใน repo ในขณะที่ฉันกำลังทำงานใน Apidog?

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

ฉันสามารถยกเลิกการเปลี่ยนแปลงก่อนที่จะถึง GitHub ได้หรือไม่?

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