Thanawat Wongchai

Posted on Jun 3 • Originally published at apidog.com

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

หาก API spec ของคุณอยู่ใน Apidog แต่ source of truth อยู่ใน Git ให้เชื่อมทั้งสองฝั่งเข้าด้วยกันด้วย Apidog Git integration เพื่อให้ OpenAPI spec ถูกพุชเข้า version control, ดึงกลับมาแก้ใน Apidog ได้ และมี audit trail สำหรับการรีวิว spec เหมือนโค้ดทั่วไป

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

บทความนี้สรุปวิธีใช้งานกับ GitHub, GitLab และ Azure DevOps รวมถึงการเลือก repo, branch, สิทธิ์การพุช, การสำรองข้อมูล และวิธีแก้ปัญหาเมื่อ sync ไม่สำเร็จ หากต้องการคู่มือเฉพาะ GitHub อ่านเพิ่มเติมได้ที่ ซิงค์ OpenAPI spec ของคุณไปยัง GitHub

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

Apidog ทำงานกับ Git ได้ 2 รูปแบบ ซึ่งควรแยกให้ชัดก่อนตั้งค่า:

ความสามารถ	ทิศทาง	Trigger	เหมาะสำหรับ
Spec-First Mode sync	สองทิศทาง: push และ pull	commit/push ด้วยตนเอง, pull ด้วยตนเอง	ทีมที่ treat API spec as code และต้องการรีวิวทุกการเปลี่ยนแปลง
Git backup อัตโนมัติ	ทางเดียว: Apidog → Git	schedule นอกเวลาทำการ	ทีมที่ต้องการ backup แบบมี version โดยไม่เปลี่ยน workflow

สรุปสั้น ๆ:

Sync = ใช้ Spec-First Mode แก้ OpenAPI ใน Apidog แล้ว push ไป Git หรือ pull จาก Git กลับมา
Backup = Apidog export OpenAPI/Swagger ไป Git ตามกำหนดเวลาแบบทางเดียว

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

Apidog รองรับ GitHub, GitLab และ Azure DevOps โดยวิธี auth จะแตกต่างกันเล็กน้อย

ผู้ให้บริการ	วิธี auth	หมายเหตุ
GitHub	OAuth ผ่าน GitHub login	ใช้ได้ทั้ง repo ส่วนตัวและองค์กร repo องค์กรอาจต้องให้ admin อนุมัติ
GitLab	OAuth ผ่าน GitLab login	รองรับ gitlab.com และ self-managed GitLab ที่ Apidog เข้าถึงได้
Azure DevOps	Generic Git Connection: HTTPS + token	ใช้ HTTPS clone URL และ personal access token ที่มีสิทธิ์ repo

Generic Git Connection ใช้ได้กับโฮสต์ Git ที่รองรับ HTTPS และ token authentication ไม่จำกัดเฉพาะ Azure DevOps เท่านั้น

ขั้นตอนเชื่อมต่อ Git provider

Workflow พื้นฐานคือ:

อนุมัติสิทธิ์ให้ Apidog
เลือก repository
เลือก branch
ตั้งค่าสิทธิ์ในทีม
เริ่ม sync หรือ backup

GitHub

เปิดการตั้งค่า Git integration ใน Apidog
เลือก GitHub
Login และอนุมัติผ่าน OAuth
เลือก repository และ branch ที่ต้องการเชื่อม
หาก repo อยู่ในองค์กร ให้ตรวจสอบว่า organization admin อนุมัติ third-party access แล้ว

หาก Apidog มองไม่เห็น repo ทั้งที่ login สำเร็จ สาเหตุที่พบบ่อยคือองค์กรยังไม่อนุมัติการเข้าถึง

GitLab

เลือก GitLab เป็น provider
Login ผ่าน GitLab OAuth
อนุมัติสิทธิ์ repository
เลือก repo และ branch

สำหรับ self-managed GitLab ต้องแน่ใจว่า Apidog เข้าถึง instance นั้นผ่าน network ได้

Azure DevOps

Azure DevOps ใช้ Generic Git Connection แทน OAuth

ขั้นตอน:

คัดลอก HTTPS clone URL ของ repo
สร้าง Personal Access Token หรือ PAT ใน Azure DevOps
ให้สิทธิ์ read/write code สำหรับ repo เป้าหมาย
ใส่ clone URL และ PAT ใน Apidog
เลือก branch ที่จะเชื่อม

แนวทางปฏิบัติที่ควรใช้:

อย่าใช้ PAT ที่มีสิทธิ์กว้างทั้งองค์กร
จำกัด scope เฉพาะ repo หรือ project ที่ต้องใช้
rotate token ตามรอบเดียวกับ secret อื่น ๆ
revoke token ทันทีเมื่อเจ้าของ token ออกจากทีม

หากต้องการวางระบบ version control สำหรับ OpenAPI ก่อนเริ่มใช้งาน อ่านเพิ่มเติมได้ที่ การควบคุมเวอร์ชัน OpenAPI ด้วย Git

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

Spec-First Mode คือ workflow สำหรับทีมที่ต้องการแก้ API spec เหมือนแก้โค้ด คุณสามารถดูเอกสารอ้างอิงได้ที่ เอกสารอย่างเป็นทางการของ Apidog

ในโหมดนี้ คุณสามารถ:

แก้ OpenAPI เป็น YAML หรือ JSON
ใช้ editor สไตล์ IDE
ตรวจ validation แบบ real-time
ใช้ autocomplete
ตรวจ $ref, schema, required fields และ syntax ระหว่างพิมพ์
commit และ push ไปยัง branch ที่เชื่อมต่อ
pull การเปลี่ยนแปลงจาก repo กลับมายัง Apidog

ตัวอย่าง endpoint ใน OpenAPI YAML:

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'

Workflow ที่แนะนำ:

Pull สถานะล่าสุดจาก repo
แก้ spec ใน Apidog
ตรวจ validation
Commit พร้อมข้อความที่ชัดเจน
Push ไปยัง branch ที่เชื่อม
เปิด pull request ใน Git provider หากใช้ feature branch
ให้ทีมรีวิว diff ของ YAML/JSON
Merge เมื่อผ่าน review

ตัวอย่าง commit message:

Add getOrder endpoint to Orders API

หลัง push สำเร็จ ตัวบ่งชี้ sync จะแสดงสถานะเช่น “Synced just now” เพื่อยืนยันว่า Apidog และ branch มีเนื้อหาเดียวกัน

หากแก้ทดลองแล้วไม่ต้องการเก็บ ให้ใช้ discard unpushed edits เพื่อย้อนกลับไปยังสถานะ sync ล่าสุด

แนวทางนี้สอดคล้องกับ เวิร์กโฟลว์ API ที่เป็น Git-native: spec เปลี่ยนผ่าน pull request, review, history และ rollback ได้เหมือน source code

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

Git backup อัตโนมัติใช้เมื่อคุณต้องการให้ Apidog export API spec ไปเก็บใน Git โดยไม่ต้องเปลี่ยน workflow รายวัน

การทำงานคือ:

เลือก module ใน Apidog
กำหนด Git repo สำหรับ backup
Apidog export OpenAPI/Swagger ของ module นั้น
ระบบ push ไปยัง repo ตาม schedule
แต่ละรอบ backup กลายเป็น commit ใน Git

สิ่งที่ควรรู้:

เป็นการ sync ทางเดียวจาก Apidog ไป Git
ไม่ pull การเปลี่ยนแปลงจาก repo กลับมา
ใช้สำหรับ backup, audit และ version history
การ push จะเกิดในช่วงนอกเวลาทำการตอนกลางคืนแบบสุ่ม
รองรับ GitHub, GitLab และ Azure DevOps

ใช้ backup เมื่อเป้าหมายคือความคงทนของ spec และประวัติการเปลี่ยนแปลง โดยไม่ต้องการให้ทีมแก้ spec ผ่าน Git โดยตรง

การเลือก repo และ branch

ก่อนเชื่อม Apidog กับ Git ให้ตัดสินใจ 2 เรื่องนี้ก่อน:

จะใช้ branch ใด
จะใช้ repo เดียวหรือหลาย repo

เลือก branch

แนวทางทั่วไป:

ใช้ main สำหรับ canonical spec
ใช้ feature branch สำหรับงานออกแบบหรือแก้ไขที่ยังไม่เสร็จ

ตัวอย่าง branch:

main
feature/add-orders-api
feature/update-auth-schema

หากเชื่อม Apidog กับ feature branch คุณจะได้ workflow แบบนี้:

แก้ spec ใน Apidog
Push ไป feature branch
เปิด pull request
ให้ทีมรีวิว API diff
Merge เข้า main

การเชื่อมตรงกับ main ทำได้ แต่ควรใช้เฉพาะทีมเล็กหรือการเปลี่ยนแปลงความเสี่ยงต่ำ เพราะจะข้าม review gate

เลือก repo

ไม่มีคำตอบเดียวที่ถูกต้อง แต่มี pattern หลักดังนี้

หนึ่ง repo ต่อหนึ่ง API

เหมาะเมื่อ:

แต่ละทีมเป็นเจ้าของ API แยกกัน
ต้องการจำกัดสิทธิ์เข้าถึง
ต้องการ history ที่อ่านง่ายต่อ API

ตัวอย่าง:

orders-api-spec/
payments-api-spec/
users-api-spec/

Monorepo สำหรับหลาย API

เหมาะเมื่อ:

ทีม platform เป็นเจ้าของ API surface หลายตัว
ต้องการรีวิวและค้นหา spec จากที่เดียว
ต้องการจัดการมาตรฐานร่วมกัน

ตัวอย่างโครงสร้าง:

api-specs/
  orders/
    openapi.yaml
  payments/
    openapi.yaml
  users/
    openapi.yaml

หากใช้ monorepo ให้แยก path ต่อ module ให้ชัด เพื่อป้องกัน backup หรือ sync ชนกัน และทำให้ diff อ่านง่ายขึ้น

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

สิทธิ์เกี่ยวข้องกับ 2 ชั้น:

สิทธิ์ใน Apidog
สิทธิ์ใน Git provider

ใน Apidog ให้กำหนดว่าใครสามารถ sync และ push ได้ จำกัดสิทธิ์ push เฉพาะเจ้าของ spec หรือ maintainer ส่วนผู้ใช้ที่แค่ดูหรือรีวิวควรมีสิทธิ์อ่าน

ใน Git provider:

GitHub/GitLab ใช้สิทธิ์ของบัญชีที่ authorize ผ่าน OAuth
Azure DevOps และ generic Git ใช้ PAT เป็น credential
PAT ต้องถูกจัดการเหมือน secret
อย่าเก็บ token ในเอกสารที่แชร์
จำกัด scope ให้แคบที่สุด
rotate และ revoke token เมื่อจำเป็น

หลักการง่าย ๆ: integration ปลอดภัยเท่ากับ token ที่อ่อนแอที่สุดในระบบ

การจัดการ merge conflicts และ drift

เมื่อ Apidog commit ไป Git จริง ๆ จึงอาจเกิด merge conflict ได้เหมือน Git ปกติ โดยเฉพาะเมื่อหลายคนแก้ YAML/JSON ส่วนเดียวกัน

ตัวอย่างสถานการณ์:

คุณแก้ Order schema ใน Apidog
เพื่อนร่วมทีมแก้ Order schema ใน repo
เพื่อนร่วมทีม push ก่อน
คุณพยายาม sync
Git พบว่า YAML บรรทัดเดียวกันถูกแก้จากสองฝั่ง

วิธีลดปัญหา:

Pull ก่อน push ทุกครั้ง
ใช้ feature branch สำหรับงานใหญ่
แยกความรับผิดชอบของ schema ให้ชัด
เขียน commit message ให้เข้าใจง่าย
รีวิว diff ก่อน merge

เมื่อเกิด conflict ให้แก้ YAML/JSON เหมือน merge conflict ปกติ:

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string

หลังแก้แล้ว ตรวจ validation ใน Apidog เพื่อให้แน่ใจว่า OpenAPI ยังถูกต้อง จากนั้น sync อีกครั้ง

สำหรับ drift หรือสถานะที่ Apidog กับ repo เริ่มไม่ตรงกัน ให้ดู indicator เช่น “Synced just now” หากไม่แสดงว่า synced ให้ตรวจว่ามี local edit ที่ยังไม่ push หรือมีการเปลี่ยนแปลงจาก repo ที่ต้อง pull หรือไม่

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

อาการ	สาเหตุที่เป็นไปได้	วิธีแก้
Authorize สำเร็จแต่ไม่พบ repo	องค์กรยังไม่อนุมัติ third-party access หรือ token scope ไม่พอ	ให้ admin อนุมัติ GitHub/GitLab app หรือออก PAT ใหม่พร้อม read/write code
Push ถูกปฏิเสธ	Token หมดอายุ ถูก revoke หรือไม่มี write permission	Authorize ใหม่ หรืออัปเดต PAT ใน Apidog
Push แล้วไม่เห็น commit ที่คาดไว้	เชื่อม branch ผิด	ตรวจ branch ที่ Apidog เชื่อมอยู่ และสลับ branch ใน project settings
สถานะ sync ค้าง	มี local edit ที่ยังไม่ push หรือจำเป็นต้อง pull	Commit/push งานค้าง หรือ pull การเปลี่ยนแปลงล่าสุดก่อน
เกิด merge conflict	มีการแก้บรรทัดเดียวกันใน spec	แก้ conflict ใน YAML/JSON ตรวจ validation แล้ว sync ใหม่
Backup ยังไม่เกิด	ยังไม่ถึง schedule นอกเวลาทำการ	รอรอบถัดไป หรือตรวจ repo/branch backup configuration
ไม่ต้องการเก็บการแก้ไขทดลอง	มี unpushed edits	ใช้ `discard unpushed edits` เพื่อย้อนกลับไปสถานะ sync ล่าสุด

ถ้าปัญหาเกิดซ้ำ ให้เริ่มจากการตรวจ credential ก่อนเสมอ โดยเฉพาะ token ที่หมดอายุ, token ถูก revoke หรือ organization approval ที่ยังไม่ครบ

FAQ

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

ขึ้นอยู่กับความสามารถที่ใช้:

Spec-First Mode เป็นสองทิศทาง: push จาก Apidog ไป Git และ pull จาก Git กลับมา
Automatic backup เป็นทางเดียว: Apidog export spec ไป Git ตาม schedule

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

อยู่ใน Git repository ที่คุณเชื่อมต่อ

Spec-First Mode: OpenAPI spec อยู่ใน branch ที่คุณ push
Backup: OpenAPI/Swagger ที่ export จากแต่ละ module ถูก commit ไป repo ที่กำหนด

ทั้งสองกรณี Git จะเก็บ version history และทีมยังควบคุม repository ได้เต็มที่

ควรซิงค์ไป branch ใด?

ใช้ main สำหรับ canonical spec และใช้ feature branch สำหรับงานที่ต้องรีวิวก่อน merge ตัวอย่างเช่น:

feature/add-payment-webhook
feature/refactor-user-schema

ถ้า token ถูก revoke จะเกิดอะไรขึ้น?

Apidog จะ push ไม่สำเร็จ เพราะไม่มีสิทธิ์เขียน ให้ authorize provider ใหม่ หรือสร้าง PAT ใหม่สำหรับ Azure DevOps/generic Git แล้วอัปเดตใน Apidog หลัง credential กลับมาใช้งานได้ sync และ backup จะทำงานต่อได้

บทสรุป

Apidog Git integration มี 2 เครื่องมือหลัก:

Spec-First Mode สำหรับทีมที่ต้องการแก้ OpenAPI spec แบบ Git-native พร้อม commit, push, pull และ review
Automatic Git backup สำหรับทีมที่ต้องการ versioned backup ของ API spec โดยไม่เปลี่ยน workflow

หากต้องการให้ API spec ผ่าน review เหมือนโค้ด ให้ตั้งค่า Spec-First Mode และใช้ feature branch + pull request หากต้องการแค่สำรองข้อมูล ให้เปิด Git backup แล้วให้ระบบ push ตอนกลางคืนอัตโนมัติ หลายทีมสามารถใช้ทั้งสองแบบร่วมกันได้: sync สำหรับงานออกแบบและ review, backup สำหรับ safety net ระยะยาว

DEV Community