Thanawat Wongchai

Posted on Jun 2 • Originally published at apidog.com

ควบคุมเวอร์ชัน OpenAPI ด้วย Git อย่างไร

#api #cicd #git #tutorial

OpenAPI spec ของคุณคือสัญญา เมื่อมันไม่สอดคล้องกัน ไคลเอนต์จะเสีย, mock จะล้าสมัย, และการทดสอบอาจผ่านกับ API ที่ไม่มีอยู่จริงอีกต่อไป วิธีจัดการที่ปลอดภัยคือปฏิบัติต่อ spec เหมือนโค้ด: เก็บใน Git, แตก branch, เปิด PR, review diff, และ validate ทุกครั้งก่อน merge

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

คู่มือนี้อธิบายวิธีควบคุมเวอร์ชัน OpenAPI ด้วย Git แบบใช้งานจริง ตั้งแต่ตำแหน่งไฟล์, กลยุทธ์ branch, checklist สำหรับ review, การ commit/push จาก Apidog, ไปจนถึง CI validation เพื่อให้ทีมมี workflow ที่ตรวจสอบได้และเชื่อถือได้

ทำไมต้องควบคุมเวอร์ชัน OpenAPI spec ของคุณ

spec ที่อยู่ใน wiki หรือ shared drive ไม่มีประวัติที่ดีพอ คุณจะตอบได้ยากว่าใครเปลี่ยน payload ของ POST /orders เมื่อไหร่ และเปลี่ยนเพราะอะไร Git แก้ปัญหานี้ได้โดยทำให้ spec กลายเป็น artifact ที่ตรวจสอบย้อนหลังได้

เมื่อใส่ openapi.yaml ไว้ใน version control คุณจะได้:

ประวัติการเปลี่ยนแปลง: ทุกการแก้ไขคือ commit ที่มีผู้เขียน เวลา และข้อความอธิบาย
Blame: ใช้ git blame openapi.yaml เพื่อดูว่าใครเพิ่ม field หรือ endpoint ใด
Rollback: ถ้า merge แล้วทำให้ contract เสีย สามารถ revert commit กลับไปยัง spec ที่ใช้งานได้
Review ก่อนใช้งานจริง: การเปลี่ยนแปลง spec ต้องผ่าน pull request เพื่อให้มีคนตรวจ diff ก่อน merge

นี่คือพื้นฐานของ เวิร์กโฟลว์ API แบบ Git-native: spec คือซอร์สโค้ด และซอร์สโค้ดควรอยู่ใน Git

ไฟล์ spec อยู่ที่ไหนใน repo

เริ่มจากโครงสร้างที่ง่ายและคาดเดาได้ ทีมส่วนใหญ่วางไฟล์ openapi.yaml ไว้ที่ root หรือในโฟลเดอร์ api/:

my-service/
├── api/
│   └── openapi.yaml
├── src/
└── README.md

ถ้าคุณต้องดูแลหลาย major version พร้อมกัน ให้แยกไฟล์ตาม version:

api/
├── api-v1.yaml
└── api-v2.yaml

แนวทางนี้ช่วยให้:

api-v1.yaml คงที่สำหรับ client เดิม
api-v2.yaml พัฒนาต่อได้โดยไม่กระทบ version เก่า
diff สั้นลง เพราะแต่ละไฟล์มีเหตุผลในการเปลี่ยนแปลงชัดเจน
review ง่ายขึ้น เพราะผู้ตรวจสอบดูเฉพาะ version ที่เกี่ยวข้อง

การปฏิบัติต่อ spec แบบนี้เป็นแนวคิดหลักของ API spec as code

เลือก convention หนึ่งแบบ แล้วบันทึกไว้ใน README หรือเอกสารของทีม สิ่งที่ควรหลีกเลี่ยงคือมีหลายไฟล์ที่ต่างก็อ้างว่าเป็น “the” spec

กลยุทธ์การแตก branch สำหรับการเปลี่ยนแปลง spec

ไม่จำเป็นต้องมี branching model แยกสำหรับ OpenAPI ใช้ workflow เดียวกับโค้ด:

git checkout main
git pull
git checkout -b api/add-refunds
# แก้ไข api/openapi.yaml
git add api/openapi.yaml
git commit -m "Add refunds endpoint to OpenAPI spec"
git push origin api/add-refunds

จากนั้นเปิด pull request ตามปกติ

รูปแบบ branch name ที่อ่านง่าย:

ประเภท Branch	รูปแบบ	ตัวอย่าง
New endpoint	`api/add-<resource>`	`api/add-refunds`
Field change	`api/change-<resource>-<field>`	`api/change-order-status`
Breaking change	`api/breaking-<description>`	`api/breaking-v2-auth`
Fix / cleanup	`api/fix-<description>`	`api/fix-pagination-schema`

คำนำหน้า api/ ช่วยให้ทุกคนรู้ทันทีว่า PR นี้เกี่ยวข้องกับ API contract และยังช่วยให้ CI หรือ automation filter branch ได้ง่ายขึ้น

สำหรับ breaking changes ให้ใช้ชื่อที่ชัดเจน เช่น api/breaking-v2-auth เพื่อส่งสัญญาณว่าต้อง review เพิ่ม และอาจต้องเพิ่ม major version

ข้อแนะนำ: รักษา branch ให้สั้นและเล็ก หนึ่ง PR ควรมีหนึ่ง logical change เท่านั้น branch ของ spec ที่ค้างหลายสัปดาห์มักชนกับการเปลี่ยนแปลงของคนอื่นและ merge ยาก

การตรวจสอบการเปลี่ยนแปลง spec ใน pull request

PR ของ spec คือการเปลี่ยน API contract ดังนั้นควร review อย่างจริงจังเหมือน production code

เขียน YAML ให้ diff อ่านง่าย เช่น ใช้ indentation สม่ำเสมอ และวางหนึ่ง property ต่อหนึ่งบรรทัด:

paths:
  /orders/{orderId}:
    get:
      summary: Get an order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"

เป้าหมายคือเมื่อเพิ่ม field หนึ่ง field diff ควรแสดงเฉพาะบรรทัดที่เกี่ยวข้อง ไม่ใช่มีการจัดรูปแบบใหม่ทั้งไฟล์

Checklist สำหรับผู้ review:

Breaking changes
- มีการเพิ่ม required field ใน request หรือไม่?
- มีการลบหรือ rename response field หรือไม่?
- enum ถูกลบค่าบางค่าออกหรือไม่?
- type ของ field เปลี่ยนหรือไม่?
Backward compatibility
- endpoint ใหม่มักปลอดภัย
- optional field ใหม่มักปลอดภัย
- การเปลี่ยน schema เดิมอาจไม่ปลอดภัย
Naming consistency
- path ใช้รูปแบบเดียวกับ API เดิมหรือไม่?
- ใช้ singular/plural สอดคล้องกันหรือไม่?
- ชื่อ field ตรงกับ convention ของทีมไหม?
Completeness
- operation ใหม่มี summary หรือไม่?
- มี response schema หรือไม่?
- มี error responses หรือไม่?
Examples
- request/response example สมจริงพอสำหรับ docs และ mock หรือไม่?

สำหรับ breaking changes อย่าพึ่ง review ด้วยสายตาอย่างเดียว ให้ใช้เครื่องมือใน CI เพื่อเปรียบเทียบ spec ของ PR กับ main แล้วทำให้ build ล้มเหลวเมื่อพบการเปลี่ยนแปลงที่ไม่ compatible

Commit & push จาก Apidog

การแก้ YAML ด้วยมือทำได้ แต่ visual editor ที่ validate แบบ real-time ช่วยลดข้อผิดพลาดและทำงานได้เร็วกว่า

โหมด Spec-First ของ Apidog รองรับ Git sync สองทาง:

เชื่อมต่อ Git repo และระบุไฟล์ spec เช่น api/openapi.yaml
แก้ไข endpoint, schema, parameters, responses และ examples ใน visual editor
Apidog เขียน YAML กลับไปยังไฟล์ spec
Commit บน branch และ push ไปยัง repo
เปิด PR เพื่อ review และ merge ตาม workflow เดิม

เนื่องจาก Apidog จัดลำดับและเขียน YAML อย่างสอดคล้องกัน diff จะยังคงเล็กและอ่านง่าย ไม่มีการ reorder หรือ reformat ที่ไม่จำเป็น

อ่านรายละเอียดเพิ่มเติมได้ที่ เอกสาร Apidog Spec-First Mode หากต้องการซิงค์กับ GitHub โดยตรง ดู การซิงค์ OpenAPI spec ของคุณไปยัง GitHub

CI validation hooks

อย่าปล่อยให้ spec ที่ไม่ถูกต้องถูก merge เข้า main ให้เพิ่ม validation เข้าไปใน pull request checks เพื่อให้ contract ที่เสียทำให้ build ล้มเหลวโดยอัตโนมัติ

ตัวอย่าง GitHub Actions ขั้นต่ำ:

name: Validate OpenAPI

on: [pull_request]

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

      - name: Lint spec
        run: npx @redocly/cli lint api/openapi.yaml

เมื่อ workflow โตขึ้น ให้เพิ่ม checks เหล่านี้:

lint โครงสร้างและ style ของ spec
ตรวจว่าไฟล์ parse เป็น OpenAPI 3.x ที่ถูกต้อง
เปรียบเทียบ spec ใน PR กับ main
fail build เมื่อพบ breaking changes

ตัวอย่าง command สำหรับตรวจ breaking changes ด้วย oasdiff:

oasdiff breaking base-openapi.yaml api/openapi.yaml

แนวทางหนึ่งคือให้ CI checkout version จาก main เป็น baseline แล้วเปรียบเทียบกับไฟล์ใน PR:

name: OpenAPI Breaking Change Check

on: [pull_request]

jobs:
  breaking-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout PR
        uses: actions/checkout@v4

      - name: Download base spec from main
        run: |
          git fetch origin main
          git show origin/main:api/openapi.yaml > base-openapi.yaml

      - name: Check breaking changes
        run: |
          npx oasdiff breaking base-openapi.yaml api/openapi.yaml

checks เหล่านี้ใช้เวลาไม่กี่วินาที แต่ช่วยจับปัญหาที่มนุษย์อาจมองข้าม เช่น field ที่ถูกลบ, required parameter ใหม่, หรือ schema type ที่เปลี่ยน

แนวทางปฏิบัติที่ดีที่สุด

ใช้ habits เหล่านี้เพื่อให้การ version control ของ spec มีสุขภาพดีในระยะยาว:

ใช้ semantic versioning
- อัปเดต info.version
- breaking change ควรเป็น major version ใหม่
- compatible addition ควรเป็น minor version
รักษา changelog
- วาง CHANGELOG.md ไว้ข้าง spec
- บอก consumer ว่าระหว่าง version มีอะไรเปลี่ยน
ส่ง PR ขนาดเล็ก
- หนึ่ง logical change ต่อ PR
- PR ใหญ่ทำให้ breaking change ซ่อนอยู่ใน diff ได้ง่าย
เขียน commit message ให้สื่อความหมาย
- ดี: Add refundReason to refund request
- ไม่ดี: Update spec
อย่าแก้ spec บน main โดยตรง
- แม้เป็น typo หรือ fix เล็ก ๆ ก็ควรแตก branch และเปิด PR
ทำให้ format คงที่
- ใช้ formatter หรือ editor ที่เขียน YAML สม่ำเสมอ
- ลด diff noise เพื่อให้ review โฟกัสที่ contract จริง

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

ฉันจะตรวจจับการเปลี่ยนแปลงที่ส่งผลกระทบใน OpenAPI spec ได้อย่างไร?

เรียกใช้เครื่องมือเปรียบเทียบ spec ใน CI โดยเปรียบเทียบ pull request กับ version บน main เครื่องมืออย่าง oasdiff สามารถจัดประเภทการเปลี่ยนแปลงเป็น breaking, non-breaking หรือ unclassified และทำให้ build ล้มเหลวเมื่อพบ breaking changes ได้

วิธีนี้ช่วยจับปัญหา เช่น field ที่ถูกลบ, required parameter ใหม่, enum value ที่หายไป และ type ที่เปลี่ยน ซึ่งการ review ด้วยตนเองอาจพลาดได้

ฉันควรรักษาไฟล์ OpenAPI ไฟล์เดียว หรือแบ่งออกเป็นหลายไฟล์?

เริ่มจากไฟล์ openapi.yaml ไฟล์เดียว เพราะ version control และ review ง่ายที่สุด

เมื่อไฟล์ใหญ่ขึ้น หรือคุณต้องดูแลหลาย major version พร้อมกัน ค่อยแบ่งตาม version เช่น:

api/
├── api-v1.yaml
└── api-v2.yaml

หรือใช้ $ref เพื่อแยก schema ไปเป็นไฟล์ย่อย อย่าแบ่งก่อนเวลาอันควร ไฟล์เดียวที่อ่านง่ายมักดีกว่าไฟล์หลายไฟล์ที่กระจัดกระจาย

ฉันสามารถควบคุมเวอร์ชัน spec โดยไม่ต้องเขียน YAML ด้วยตนเองได้หรือไม่?

ได้ โหมด Spec-First ของ Apidog ช่วยให้คุณแก้ไข spec ผ่าน visual editor และซิงค์การเปลี่ยนแปลงไปยัง Git ได้ทั้งสองทิศทาง คุณยังคงได้ประโยชน์จาก Git history, branch, commit, pull request และ review เต็มรูปแบบ โดยไม่ต้องจัดการ YAML ทุกบรรทัดด้วยมือ

DEV Community