การทำงานร่วมกันแบบ Git-native สำหรับการทดสอบและวิศวกรรม API

OpenAPI spec ของคุณคือสัญญาที่เชื่อมโยง API ของคุณกับผู้ใช้งาน แต่สัญญานั้นอยู่ที่ไหน?

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

โหมด Spec-first พลิกโมเดลนี้ ไฟล์ OpenAPI หรือ Swagger ของคุณจะกลายเป็นแหล่งข้อมูลที่น่าเชื่อถือ (source of truth) ซึ่งจัดเก็บโดยตรงในที่เก็บ Git ของคุณควบคู่ไปกับโค้ดการนำไปใช้งาน การเปลี่ยนแปลง spec ทุกครั้งจะไหลผ่านสาขา (branches), คำขอรวมโค้ด (pull requests) และกระบวนการตรวจสอบแบบเดียวกับที่คุณใช้อยู่แล้ว การออกแบบ API, การทดสอบ และ เอกสารประกอบ ทั้งหมดจะซิงโครไนซ์กันโดยอัตโนมัติ

ในบทช่วยสอนนี้ ผมจะแนะนำวิธีการตั้งค่าโปรเจกต์ Spec-first ใน Apidog, การแก้ไขข้อกำหนดกับทีมของคุณ และการรักษาทุกอย่างให้ซิงค์กับเวิร์กโฟลว์ Git ของคุณ

โหมด Spec-first คืออะไร?

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

โหมด Spec-first แตกต่างออกไป พื้นที่ทำงานหลักจะอิงตามไฟล์:

• openapi.yaml หรือ openapi.json อยู่ใน repo ของคุณ
• Apidog วิเคราะห์ไฟล์เหล่านี้และสร้างโครงสร้าง API ที่สามารถนำทางได้
• คุณแก้ไขไฟล์โดยตรง (หรือผ่านฟอร์มที่รองรับ)
• การเปลี่ยนแปลงจะซิงค์กลับไปยัง Git โดยอัตโนมัติ

ไฟล์ข้อกำหนดเป็นข้อมูลหลักเสมอ Apidog อ่านจากไฟล์ เขียนไปยังไฟล์ และรักษาให้ซิงโครไนซ์กับที่เก็บของคุณ

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

ในการทำตาม คุณจะต้องมี:

• บัญชี Apidog (แบบฟรีก็ใช้ได้)
• ที่เก็บ Git ที่มีไฟล์ OpenAPI/Swagger หรือที่เก็บเปล่าเพื่อเริ่มต้นใหม่
• สิทธิ์ในการเขียน ไปยังที่เก็บ
• ความคุ้นเคยเบื้องต้นกับ ไวยากรณ์ OpenAPI หรือ Swagger

ขั้นตอนที่ 1: สร้างโปรเจกต์ Spec-first

คลิก + โปรเจกต์ใหม่ ใน Apidog และเลือก โหมด Spec-first เป็นประเภทโปรเจกต์

ถัดไป เชื่อมต่อผู้ให้บริการ Git ของคุณ:

1. เลือกผู้ให้บริการของคุณ (GitHub, GitLab, Azure DevOps, หรือ Bitbucket)
2. เลือกองค์กรหรือพื้นที่ทำงาน
3. เลือกที่เก็บที่มีอยู่หรือสร้างใหม่
4. เลือก branch หลักสำหรับการซิงโครไนซ์

Apidog จะซิงค์กับ branch เริ่มต้นของที่เก็บของคุณ หากไม่ได้ชื่อ main Apidog จะปรับให้โดยอัตโนมัติ

ขั้นตอนที่ 2: กำหนดค่า Webhook Sync (แนะนำ)

ระหว่างการตั้งค่า คุณจะเห็นตัวเลือกในการติดตั้ง webhook ซึ่งช่วยให้การซิงโครไนซ์อัตโนมัติทำงานเมื่อใดก็ตามที่ทีมของคุณ push ไปยังที่เก็บ

หมายเหตุ: การติดตั้ง Webhook โดยทั่วไปต้องใช้ สิทธิ์ผู้ดูแลระบบ บนที่เก็บ หากคุณไม่มีสิทธิ์ผู้ดูแลระบบ ให้ข้ามขั้นตอนนี้—คุณยังคงสามารถซิงค์ด้วยตนเองได้โดยใช้ Git Pull

ประโยชน์ของ Webhook:

• ทีม push การเปลี่ยนแปลง → Apidog ซิงค์โดยอัตโนมัติ
• ไม่จำเป็นต้องรีเฟรชด้วยตนเอง
• ทุกคนเห็นสถานะ spec ล่าสุด

หากคุณข้ามการตั้งค่า webhook ในตอนแรก คุณสามารถเพิ่มได้ในภายหลังจาก การตั้งค่าโปรเจกต์ > Git & Branches

ขั้นตอนที่ 3: สำรวจพื้นที่ทำงาน Specs

หลังจากสร้าง โปรเจกต์ของคุณจะเปิดพื้นที่ทำงาน Specs ซึ่งเป็นศูนย์กลางสำหรับการแก้ไขไฟล์และการดำเนินการ Git

สามแผงทำงานร่วมกัน:

คลิก endpoint ในโครงสร้างแบบ tree → Apidog จะเน้นส่วนที่เกี่ยวข้องในไฟล์ต้นฉบับของคุณ เลื่อนจากมุมมอง API ระดับสูงไปยัง YAML ระดับต่ำได้โดยไม่ต้องสลับแท็บ

ขั้นตอนที่ 4: แก้ไขไฟล์ข้อกำหนดของคุณ

มุมมองโค้ด: การแก้ไขโดยตรง

สำหรับไฟล์ส่วนใหญ่—YAML, JSON, Markdown—ใช้ มุมมองโค้ด เพื่อแก้ไขข้อความดิบ

การแก้ไขของคุณจะอยู่ในไฟล์ Apidog จะไม่แปลงหรือจัดเก็บแยกต่างหาก ไฟล์ spec ยังคงเป็นแหล่งข้อมูลหลักเพียงแหล่งเดียว

มุมมองฟอร์ม: การแก้ไขที่มีโครงสร้าง

สำหรับโหนด OpenAPI ที่รองรับ—endpoints, schemas, definitions และภาพรวม API—ให้เปลี่ยนไปที่ มุมมองฟอร์ม

มุมมองฟอร์มมีประโยชน์เมื่อ:

• การเพิ่ม endpoints ที่มีฟิลด์ที่จำเป็นทั้งหมดโดยไม่ต้องจำโครงสร้าง YAML
• การแก้ไข schemas ด้วยภาพ
• การอัปเดตคำจำกัดความความปลอดภัยและเมตาดาต้า API

หากโหนดไม่รองรับการแก้ไขฟอร์ม Apidog จะให้คุณอยู่ในมุมมองโค้ด

ขั้นตอนที่ 5: ตรวจสอบและดูตัวอย่างทันที

โหมด Spec-first มีการตรวจสอบความถูกต้องแบบเรียลไทม์และการดูตัวอย่างเอกสาร—ไม่จำเป็นต้องใช้เครื่องมือภายนอก

ตรวจสอบปัญหาด้วยการตรวจสอบความถูกต้อง

คลิก Validation ในส่วนหัวของตัวแก้ไข แผงจะแสดงคำเตือนและข้อผิดพลาดทั้งหมดใน spec ปัจจุบันของคุณ

ป้ายจะแสดงจำนวนปัญหารวม ตรวจจับ:

• ข้อผิดพลาดทางไวยากรณ์
• ฟิลด์ที่จำเป็นขาดหายไป
• การละเมิด Schema
• ปัญหาเรื่องกฎการตั้งชื่อ

แก้ไขปัญหาก่อนที่จะ commit ผู้ตรวจสอบของทีมคุณไม่จำเป็นต้องตรวจสอบด้วยตนเอง

ดูตัวอย่างเอกสารประกอบของคุณ

คลิก Preview เพื่อดูว่า spec ของคุณจะแสดงผลเป็นเอกสาร API อย่างไร

สำหรับ endpoints การดูตัวอย่างจะมีสองแท็บ:

สำหรับ schemas และ definitions การดูตัวอย่างจะแสดงมุมมองเอกสารที่แสดงผล

Validation และ Preview ใช้แผงด้านข้างเดียวกัน การเปิดอันใดอันหนึ่งจะปิดอีกอันโดยอัตโนมัติ

ขั้นตอนที่ 6: ดึงข้อมูลอัปเดตจากทีมของคุณ

เมื่อผู้ทำงานร่วมกัน push การเปลี่ยนแปลงไปยังที่เก็บของคุณ ให้นำการเปลี่ยนแปลงเหล่านั้นเข้ามาใน Apidog:

1. เปิดพื้นที่ทำงาน Specs
2. คลิกชื่อ branch ปัจจุบันในแถบด้านข้าง
3. เลือก Git Pull

หาก webhook sync ทำงานอยู่ Apidog จะดึงข้อมูลโดยอัตโนมัติเมื่อมีเหตุการณ์ push ไปยังที่เก็บ—ไม่จำเป็นต้องทำด้วยตนเอง

ขั้นตอนที่ 7: Commit และ Push การเปลี่ยนแปลงของคุณ

หลังจากแก้ไขไฟล์ใน Apidog แล้ว ให้ส่งการอัปเดตของคุณกลับไปยัง Git:

1. ทำการเปลี่ยนแปลงในพื้นที่ทำงาน Specs
2. คลิก Changes ในแถบด้านข้างเพื่อดูไฟล์ที่ถูกแก้ไข เพิ่ม เปลี่ยนชื่อ และลบ
3. คลิก Commit & Push
4. เลือกไฟล์ที่จะรวม
5. เขียนข้อความ commit
6. คลิก Push

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

เคล็ดลับ: ใช้ Discard all changes หากคุณต้องการละทิ้งการแก้ไขในเครื่องก่อนที่จะ push

ขั้นตอนที่ 8: ทำงานกับ Branches

โหมด Spec-first รองรับการทำงานร่วมกันแบบ branch อย่างเต็มรูปแบบ Apidog จะแมป Git branches เข้ากับ project branches ทำให้คุณสามารถสลับระหว่างเวอร์ชันของ spec ได้

การดำเนินการ Branch ทั่วไป

การจัดการ branch ทำงานในลักษณะเดียวกับที่คุณคาดหวังจาก Git—feature branches, releases และการพัฒนาคู่ขนานทั้งหมดจะซิงค์อย่างถูกต้อง

ขั้นตอนที่ 9: ผสานรวมกับ CI/CD

เนื่องจาก spec ของคุณอยู่ใน Git จึงเข้ากันได้ดีกับ pipeline ระบบอัตโนมัติ:

• Lint specs ในทุก PR โดยใช้การตรวจสอบของ Apidog หรือเครื่องมือเช่น Spectral
• สร้างเอกสารประกอบ โดยอัตโนมัติเมื่อ specs รวมเข้ากับ main
• รันการทดสอบ API ที่ถูกกระตุ้นโดยการเปลี่ยนแปลง spec
• ซิงค์ไปยังระบบปลายน้ำ—API gateways, mock servers, SDK generators

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

ข้อกำหนด API ของคุณตอนนี้ผ่านเกณฑ์คุณภาพเดียวกันกับโค้ดแอปพลิเคชันของคุณ

ทางเลือก: โปรเจกต์ที่เก็บข้อมูลภายใน

หากคุณยังไม่พร้อมที่จะเชื่อมต่อที่เก็บ Git ภายนอก Apidog มีโปรเจกต์ Spec-first ที่ใช้ พื้นที่เก็บข้อมูลภายใน (storage-backed) ให้บริการ

โปรเจกต์เหล่านี้ใช้พื้นที่เก็บข้อมูลภายในของ Apidog แต่ยังคงมีให้:

• การแก้ไขไฟล์
• การตรวจสอบความถูกต้องและดูตัวอย่าง
• การจัดการ Branch

ป้าย UI จะปรับเปลี่ยนเล็กน้อย:

• Git Pull กลายเป็น Sync
• Commit & Push กลายเป็น Save

ย้ายไปยัง Git ภายนอกได้ทุกเมื่อที่ทีมของคุณพร้อม

สรุป

ด้วยโหมด Spec-first เวิร์กโฟลว์ API ของคุณจะกลายเป็น:

โหมด Spec-first ทำให้ไฟล์ OpenAPI เป็นสัญญาที่ควรจะเป็น—มีการกำหนดเวอร์ชัน ตรวจสอบ และสอดคล้องกับโค้ดของคุณเสมอ

พร้อมที่จะลองใช้หรือไม่? สร้างโปรเจกต์ Spec-first ใน Apidog และเชื่อมต่อที่เก็บแรกของคุณ