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

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

ลองใช้ Apidog วันนี้

บทความนี้จะแสดงขั้นตอนการซิงค์ OpenAPI spec กับ GitHub ด้วย Spec-First Mode ของ Apidog ตั้งแต่เชื่อมต่อ Git provider, เปิดโปรเจกต์จาก repository, แก้ไข YAML, commit และ push กลับไปยัง GitHub โดยไม่ต้อง export/import เอง ขั้นตอนเดียวกันนี้ใช้กับ GitLab ได้ และ Azure DevOps รองรับผ่าน Git Connection

การซิงค์สองทางคืออะไร

การซิงค์สองทางหมายถึงการเปลี่ยนแปลง OpenAPI spec ไหลได้ทั้งสองทิศทางโดยไม่ต้องมีขั้นตอน export/import คั่นกลาง

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

แนวคิดคือให้ repository เป็น single source of truth ส่วน Apidog ทำหน้าที่เป็น editor ที่ทำงานอยู่บน Git repo โดยตรง นี่คือหลักของ เวิร์กโฟลว์ API แบบ Git-native: spec ถูก version, review และติดตาม history เหมือนไฟล์อื่นใน codebase แทนที่จะอยู่ในเครื่องมือแยกต่างหากแล้วค่อย export snapshot เป็นระยะ

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

ก่อนเริ่ม ให้เตรียมสิ่งต่อไปนี้:

• บัญชี Apidog และเข้าถึงแอปเดสก์ท็อปหรือเว็บได้
• GitHub หรือ GitLab repository ที่มีไฟล์ OpenAPI อยู่แล้ว เช่น openapi.yaml, openapi.json หรือไฟล์ภายใต้ docs/
• สิทธิ์เขียนบน branch ที่ต้องการ sync
• เปิดใช้ Spec-First Mode (beta) ใน Apidog
• หากใช้ Azure DevOps ให้เชื่อมต่อผ่าน Git Connection

ถ้าคุณมีสิทธิ์อ่านอย่างเดียว คุณจะเปิดและดึง spec ได้ แต่จะ push commit กลับ repo ไม่ได้

ขั้นตอนที่ 1: เชื่อมต่อ Git provider

เริ่มจากให้สิทธิ์ Apidog เข้าถึง repository ที่ต้องการ sync

1. เปิด Apidog
2. สร้างโปรเจกต์ใหม่
3. เลือก Spec-First Mode
4. เมื่อระบบถามแหล่งที่มา ให้เลือก Git provider เช่น GitHub หรือ GitLab
5. คลิก Authorize
6. เบราว์เซอร์จะเปิดหน้าจอ OAuth ของ provider
7. อนุญาตให้ Apidog เข้าถึง repository ที่ต้องการ

บน GitHub คุณสามารถจำกัด scope เฉพาะ repository ที่ต้องการได้ แนะนำให้ให้สิทธิ์เฉพาะ repo ที่เกี่ยวข้องแทนการให้สิทธิ์ทั้งบัญชี

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

อ่านรายละเอียดเพิ่มเติมเกี่ยวกับ Spec-First Mode และ Azure DevOps ผ่าน Git Connection ได้ที่ เอกสาร Spec-First Mode

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

เมื่อเชื่อมต่อ provider แล้ว ให้ชี้ Apidog ไปยังไฟล์ OpenAPI ใน repo

1. เลือก repository ที่เก็บ OpenAPI spec
2. เลือก branch ที่ต้องการ sync เช่น main
3. ระบุ path ของไฟล์ OpenAPI หากระบบถาม เช่น:
   • openapi.yaml
   • docs/openapi.yaml
   • specs/public-api.yaml
4. สร้างโปรเจกต์

Apidog จะโหลด spec จาก branch ที่เลือกและเปิดใน editor จากนั้น sidebar ด้านซ้ายจะแสดง endpoints และ schemas ที่ parse มาจากไฟล์ OpenAPI

ณ จุดนี้คุณไม่ได้แก้ไขสำเนาแยกอีกชุดหนึ่ง แต่กำลังทำงานกับ spec ที่ผูกกับ repository โดยตรง

ขั้นตอนที่ 3: แก้ไข OpenAPI YAML ใน editor

Spec-First Mode มี editor สำหรับ OpenAPI YAML พร้อม syntax highlighting, inline validation และ autocomplete คุณจึงแก้ไข spec เป็น YAML ได้โดยตรง ในขณะที่ Apidog อัปเดตโครงสร้าง API ใน sidebar ตามเนื้อหาที่คุณเขียน

ตัวอย่าง: เพิ่ม health check endpoint

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

ระหว่างแก้ไข ควรตรวจสอบ 3 จุดนี้ก่อน commit:

1. โครงสร้าง endpoint ใน sidebar
   
   ตรวจว่า /health ปรากฏในรายการ endpoint แล้ว

2. inline validation
   
   แก้ error เช่น:

   • responses หาย
   • $ref ชี้ผิด path
   • indentation ผิด
   • schema ไม่ถูกต้องตาม OpenAPI format

3. YAML formatting
   
   OpenAPI YAML อ่อนไหวต่อ indentation มาก แนะนำให้ตรวจ indentation ก่อน commit ทุกครั้ง

หากต้องการเข้าใจการทำงานร่วมกับ diff และ history เพิ่มเติม อ่านต่อได้ที่ การควบคุมเวอร์ชัน OpenAPI ด้วย Git

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

เมื่อแก้ไขเสร็จและ validation ผ่าน ให้ส่งการเปลี่ยนแปลงกลับไปยัง repository

1. เปิดแผง Git หรือ source control ในโปรเจกต์
2. ตรวจ diff ของไฟล์ OpenAPI
3. เขียน commit message เช่น:

Add /health endpoint

1. คลิก Commit & Push

หลัง push สำเร็จ ให้เปิด repository บน GitHub แล้วตรวจสอบว่า commit ปรากฏใน branch history ตามปกติ การเปลี่ยนแปลงจะอยู่ในไฟล์ OpenAPI ที่คุณแก้ไข และ author จะเป็นบัญชีของคุณตามสิทธิ์ Git ที่เชื่อมต่อไว้

หากแก้ไขแล้วเปลี่ยนใจก่อน push ให้ใช้คำสั่ง discard unpushed edits เพื่อย้อน spec กลับไปยังสถานะล่าสุดที่ sync กับ repo แล้ว การเปลี่ยนแปลงจะยังไม่ออกจาก Apidog จนกว่าคุณจะ commit และ push

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

Apidog จะแสดง sync indicator เพื่อบอกสถานะระหว่าง editor กับ remote branch

หลัง push สำเร็จ คุณควรเห็นสถานะประมาณว่า:

Synced just now

หมายความว่า spec ใน Apidog และ spec บน remote branch ตรงกันแล้ว

เมื่อเวลาผ่านไป indicator จะอัปเดต เช่น:

Synced 5 minutes ago

หากเพื่อนร่วมทีม push การเปลี่ยนแปลงเข้ามา Apidog จะดึงข้อมูลล่าสุดและอัปเดต editor ให้สอดคล้องกับ repo

ถ้า indicator แสดงว่าสำเนาในเครื่องล้าสมัยหรือมี pending changes ให้หยุดตรวจสอบก่อนทำงานต่อ เพื่อป้องกันการแก้ไขทับกันบน branch เดียวกัน

การแก้ไขปัญหาที่พบบ่อย

Push ไม่ได้เพราะ permission error

สาเหตุที่พบบ่อย:

• OAuth token หมดอายุ
• token ถูก revoke จากฝั่ง Git provider
• บัญชีไม่มีสิทธิ์เขียน repo หรือ branch

วิธีแก้:

1. กลับไป authorize Git provider ใหม่
2. ตรวจสิทธิ์ของบัญชีบน repository
3. ตรวจว่า branch ที่เลือกอนุญาตให้ push ได้

Push ไปยัง branch ที่ protected ไม่ได้

หาก branch เช่น main ถูกตั้งค่าให้ต้องผ่าน pull request ก่อน การ push ตรงจาก Apidog อาจถูกปฏิเสธ

ทางเลือก:

• sync กับ branch สำหรับงาน เช่น feature/update-openapi
• push แล้วเปิด pull request ตาม workflow ของทีม
• ปรับ branch protection rule หากเหมาะสมกับนโยบายทีม

เกิด merge conflict

ถ้าเพื่อนร่วมทีมแก้ไข spec บน branch เดียวกันในขณะที่คุณกำลังแก้ไขอยู่ remote อาจเดินหน้าไปก่อน local copy

วิธีจัดการ:

1. ดึงข้อมูลล่าสุดจาก branch
2. ตรวจส่วน YAML ที่ conflict
3. แก้ conflict เหมือนไฟล์ text ปกติ
4. ตรวจ validation อีกครั้ง
5. commit และ push ใหม่

เพราะ OpenAPI spec เป็นไฟล์ข้อความ conflict จึงจัดการได้เหมือน code file อื่นใน Git

Inline validation แจ้ง error

Apidog อาจไม่บังคับให้คุณหยุด commit ทุกกรณี แต่ควรแก้ validation warning/error ก่อน push โดยเฉพาะปัญหาเหล่านี้:

• missing required fields
• $ref ผิด
• schema type ไม่ตรง
• response object ไม่สมบูรณ์
• YAML indentation ผิด

spec ที่ถูกต้องช่วยให้เอกสาร generated docs, mock server และ test workflow ทำงานได้แม่นยำขึ้น

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

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

ได้ Spec-First Mode รองรับ GitHub และ GitLab โดยตรง ส่วน Azure DevOps ใช้ผ่าน Git Connection ขั้นตอนหลักเหมือนกันคือ connect, edit, commit และ push แตกต่างกันเฉพาะหน้าจอ authorization ของแต่ละ provider

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

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

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

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