Thanawat Wongchai

Posted on Jun 2 • Originally published at apidog.com

Git-Native API Workflow คืออะไร? สร้างได้อย่างไร

โค้ดของคุณอยู่ใน Git. CI pipeline, การรีวิว, และประวัติการเผยแพร่ของคุณก็อยู่ใน Git. แล้วทำไม API spec ของคุณถึงต้องไปอยู่ในที่อื่น?

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

เวิร์กโฟลว์ API แบบ Git-native คือการเก็บ OpenAPI definition ไว้ใน repository เดียวกับโค้ดของคุณ แก้ไข spec เป็นไฟล์ YAML หรือ JSON, commit, push, และรีวิวผ่าน pull request เหมือนกับไฟล์อื่น ๆ ในโปรเจกต์ ไม่มีฐานข้อมูลคลาวด์แยกต่างหาก ไม่มีขั้นตอน export/import และไม่มีแหล่งความจริงหลายชุด

Apidog รองรับแนวทางนี้ผ่าน Spec-First Mode: คุณออกแบบ API ใน editor สไตล์ IDE แล้วซิงค์ไฟล์ดิบแบบสองทางกับ GitHub หรือ GitLab บทความนี้จะแสดงว่าเวิร์กโฟลว์ API แบบ Git-native ทำงานอย่างไร ปัญหาของ spec ที่ถูกล็อคไว้กับคลาวด์คืออะไร และจะตั้งค่า Spec-First Mode อย่างไรแบบทีละขั้นตอน

เวิร์กโฟลว์ API แบบ Git-native หมายถึงอะไร

เวิร์กโฟลว์ API แบบ Git-native ถือว่า API spec เป็นโค้ด ไฟล์ OpenAPI อยู่ใน repository เดียวกับ service ทุกการเปลี่ยนแปลงคือ commit และทุก commit มีผู้เขียน ข้อความ และ diff ที่ตรวจสอบได้

สิ่งที่คุณได้จากการเก็บ spec ไว้ใน Git:

ประวัติเวอร์ชัน: ดูได้ว่าใครเปลี่ยน endpoint เมื่อไหร่ ใช้ git blame กับ spec ได้
Branch และ review: การเปลี่ยนแปลง spec ผ่าน pull request ผู้รีวิวเห็น diff ก่อน merge
แหล่งความจริงเดียว: ไฟล์ใน main คือ API contract ที่เครื่องมือ เอกสาร และ mock ใช้อ้างอิง

แนวคิดนี้สอดคล้องกับการทำงานแบบ spec-first: กำหนดสเปคก่อน แล้ว implementation ทำตาม อ่านเพิ่มเติมได้ในคู่มือ การพัฒนา API แบบ spec-first

แนวทางตรงข้ามคือการเก็บ spec ไว้ในแอปพลิเคชันคลาวด์ที่เป็นกรรมสิทธิ์ ซึ่งอาจใช้งานได้ในช่วงแรก แต่จะเริ่มสร้าง friction เมื่อทีมใหญ่ขึ้นหรือ workflow ซับซ้อนขึ้น

ปัญหาของ API spec ที่ถูกล็อคไว้กับคลาวด์

เครื่องมือออกแบบ API จำนวนมากเก็บ spec ไว้ในฐานข้อมูลของตัวเอง คุณแก้ไขผ่าน UI ของเครื่องมือ และ “ไฟล์” ที่ทีมคิดว่าเป็นเจ้าของจริง ๆ แล้วอาจเป็นเพียงข้อมูลในระบบของผู้ให้บริการ

ปัญหาที่มักเกิดขึ้น:

การรีวิวแยกเป็นสองที่: โค้ดรีวิวใน GitHub แต่ spec รีวิวในเครื่องมืออีกตัว ผู้รีวิวต้องสลับ context และการอนุมัติอาจไม่สอดคล้องกัน
Diff ไม่ชัดเจน: เมื่อ spec อยู่ในฐานข้อมูลคลาวด์ คุณไม่เห็น diff แบบบรรทัดต่อบรรทัดใน pull request
Export/import เพิ่มขั้นตอน: หากต้องนำ spec เข้า CI คุณต้อง export, commit, แล้วหวังว่าไม่มีใครแก้ไข spec บนคลาวด์ระหว่างนั้น
Automation ทำงานยากขึ้น: Linters, contract tests และ code generators ต้องการไฟล์บนดิสก์ หาก spec อยู่บนคลาวด์ คุณต้องเพิ่มขั้นตอน fetch ก่อนเสมอ

การปฏิบัติต่อ API spec เหมือนโค้ดช่วยลดปัญหาเหล่านี้ ไฟล์คือ spec, Git คือประวัติ และ pipeline เดิมของคุณจัดการส่วนที่เหลือได้ อ่านเพิ่มเติมได้ใน API spec as code

Apidog Spec-First Mode ทำงานอย่างไร

Spec-First Mode เหมาะกับทีมที่ใช้ commit, branch และ pull request เป็น workflow หลัก คุณออกแบบ API เป็นไฟล์ YAML หรือ JSON ดิบ แล้ว Apidog ซิงค์ไฟล์เหล่านั้นกับ Git repo แบบสองทาง

1. เขียน OpenAPI ใน editor สไตล์ IDE

แทนที่จะกรอกฟอร์ม คุณเขียน spec ใน code editor ที่รองรับ:

Syntax highlighting สำหรับ YAML และ JSON
Validation ตาม OpenAPI และ Swagger schemas
Auto-completion สำหรับ keywords, types และ references ของ OpenAPI

คุณยังควบคุมไฟล์จริงทั้งหมด ไม่มีฟิลด์ที่ซ่อนอยู่หรือ metadata ที่ดูได้เฉพาะใน UI

2. ใช้ไฟล์ YAML/JSON ดิบเป็น contract

ตัวอย่าง OpenAPI spec:

openapi: 3.1.0
info:
  title: Orders API
  version: 1.2.0
paths:
  /orders/{orderId}:
    get:
      summary: Get an order by ID
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]

นี่คือไฟล์ที่อยู่ใน repo และเป็นไฟล์เดียวกับที่จะถูก commit

3. นำทาง spec ขนาดใหญ่ด้วย outline

ระหว่างที่คุณพิมพ์ Apidog จะแยกวิเคราะห์ไฟล์และสร้าง outline ในแถบด้านข้าง เช่น paths, operations และ schemas คุณสามารถคลิกเพื่อข้ามไปยัง endpoint หรือ schema ได้ทันที โดยไม่ต้องเลื่อนผ่านหลายร้อยบรรทัด

4. ซิงค์ Git แบบสองทาง

Spec-First Mode เชื่อมต่อกับ Git provider และซิงค์การเปลี่ยนแปลงทั้งสองทิศทาง รองรับ GitHub และ GitLab โดยตรง และ Azure DevOps ผ่าน Git Connection

Workflow หลักคือ:

pull -> edit -> commit -> push -> verify sync

คุณสามารถดึงการเปลี่ยนแปลงที่เพื่อนร่วมทีม push เข้ามา แก้ไขใน Apidog แล้ว commit/push กลับไปยัง branch เดิม

5. Commit, push และตรวจสอบสถานะ sync

คุณไม่จำเป็นต้องออกจาก Apidog เพื่อจัดการ Git สามารถ stage changes, เขียน commit message และ push ได้จากในเครื่องมือ ตัวบ่งชี้สถานะ sync จะแจ้งสถานะปัจจุบัน หลัง push สำเร็จจะแสดงว่า "Synced just now."

หากเปลี่ยนใจก่อน push คุณสามารถ discard การแก้ไขที่ยังไม่ได้ push และย้อนกลับไปยังสถานะที่ sync ล่าสุดได้

อ่านขั้นตอนเพิ่มเติมสำหรับ GitHub ได้ที่ ซิงค์ OpenAPI spec ไปยัง GitHub

วิธีตั้งค่า Spec-First Mode

ขั้นตอนจาก repo ไปสู่ spec ที่ซิงค์แล้วมีดังนี้ อ้างอิงฉบับเต็มดูได้ใน เอกสาร Spec-First Mode

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

ใน Apidog ให้สร้างโปรเจกต์ Spec-First ใหม่ แล้วเชื่อมต่อ Git provider ของคุณ เลือก repository ที่เก็บ API spec และเลือก branch ที่ต้องการติดตาม โดยทั่วไปคือ main

Apidog จะดึงไฟล์ spec ที่มีอยู่เข้ามาใน editor

ขั้นตอนที่ 2: แก้ไข spec

เปิดไฟล์ OpenAPI ใน editor แล้วเพิ่ม endpoint, ปรับ schema หรือแก้ไข response ตัวอย่างเช่นเพิ่ม 404 response ให้ operation เดิม:

responses:
  "200":
    description: Order found
  "404":
    description: Order not found

ระหว่างแก้ไข editor จะช่วยด้วย syntax highlighting, validation และ auto-completion ส่วน outline ด้านซ้ายจะอัปเดตตามไฟล์

ขั้นตอนที่ 3: ตรวจสอบไฟล์ที่เปลี่ยนแปลง

Apidog จะแสดงไฟล์ที่ถูกแก้ไข เพิ่ม หรือลบตั้งแต่การ sync ครั้งล่าสุด เพื่อให้คุณรู้ว่า commit ถัดไปจะรวมอะไรบ้าง

ขั้นตอนที่ 4: เขียน commit message

ใช้ข้อความ commit ที่อธิบายการเปลี่ยนแปลงชัดเจน เช่น:

Add 404 response to getOrder

หลีกเลี่ยงข้อความกว้าง ๆ เช่น:

update spec

ขั้นตอนที่ 5: Push ไปยัง branch

Push commit ไปยัง branch ที่ติดตาม จากนั้นทีมและ CI pipeline จะเห็น spec เวอร์ชันใหม่

ขั้นตอนที่ 6: ตรวจสอบสถานะ sync

ดูตัวบ่งชี้สถานะ sync หากแสดง "Synced just now." แปลว่า local changes และ remote branch ตรงกันแล้ว จากนั้นการเปลี่ยนแปลงจะไหลต่อไปตาม pull request และ review process ปกติของทีม

สรุป workflow:

pull
edit OpenAPI YAML/JSON
review changed files
commit
push
verify "Synced just now"

ไม่มี export ไม่มี import และไม่มีแหล่งความจริงที่สอง

Spec-first เทียบกับ Design-first mode

Apidog รองรับสองวิธีทำงานหลัก ความต่างคือ spec อยู่ที่ไหนและคุณแก้ไขอย่างไร

หัวข้อ	Spec-First Mode (เบต้า)	Design-First Mode
การจัดเก็บ Spec	ไฟล์ YAML/JSON ดิบใน Git	โปรเจกต์ Apidog บนคลาวด์
Editor หลัก	Code editor สไตล์ IDE	UI แบบฟอร์มที่มองเห็นได้
การควบคุมเวอร์ชัน	Git ดั้งเดิม เช่น commits, branches, diffs	ประวัติและ branches ของ Apidog
การซิงค์ Git แบบสองทาง	มี รองรับ GitHub, GitLab, Azure DevOps	ผ่านการส่งออก/นำเข้า
เหมาะสำหรับ	ทีมที่ทำงานกับ Git เป็นหลัก	ทีมที่ชอบ workflow แบบภาพ

ไม่มีโหมดใดดีกว่าเสมอไป หาก review และ release process ของคุณอยู่บน Git อยู่แล้ว Spec-First Mode จะลดความซับซ้อน แต่ถ้าทีมออกแบบ API ผ่าน UI เป็นหลักและไม่ค่อยแตะ OpenAPI ดิบ Design-First Mode อาจเหมาะกว่า

ควรใช้ Spec-First Mode เมื่อใด

เลือกใช้ Spec-First Mode เมื่อ:

API spec ควรผ่าน pull request และ code review
คุณต้องการ git blame และ commit history จริงบน API contract
CI รัน spec linting, contract tests หรือ code generation ที่ต้องการไฟล์บนดิสก์
วิศวกรหลายคนแก้ไข spec และต้องการ diff ที่สะอาดและ merge ได้
คุณต้องการลดขั้นตอน export/import ระหว่างเครื่องมือ

ใช้แนวทางแบบ visual หรือ cloud-first ต่อไปเมื่อทีมออกแบบ API โดยไม่เขียน OpenAPI ดิบ หรือเมื่อเจ้าของ spec เป็นผู้ที่ไม่ใช่วิศวกรและต้องการ editor แบบฟอร์ม

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

เวิร์กโฟลว์ API แบบ Git-native คืออะไร?

เวิร์กโฟลว์ API แบบ Git-native คือการเก็บ OpenAPI spec เป็นไฟล์ใน Git repository และจัดการทุกการเปลี่ยนแปลงผ่าน commits, branches และ pull requests ทำให้ spec ใช้กระบวนการ review และ version control เดียวกับโค้ดแอปพลิเคชัน

Apidog Spec-First Mode รองรับ GitHub และ GitLab หรือไม่?

รองรับ Spec-First Mode ซิงค์แบบสองทางกับ GitHub และ GitLab โดยตรง ส่วน Azure DevOps รองรับผ่าน Git Connection คุณเชื่อมต่อ repo, เลือก branch แล้ว Apidog จะรักษาการแก้ไขและ remote ให้ sync กัน

แก้ไขไฟล์ OpenAPI เป็น YAML หรือ JSON ดิบได้หรือไม่?

ได้ Spec-First Mode มี editor สไตล์ IDE สำหรับ YAML และ JSON ดิบ พร้อม syntax highlighting, schema validation และ auto-completion สำหรับ OpenAPI และ Swagger นอกจากนี้ outline ด้านซ้ายจะ parse ไฟล์โดยอัตโนมัติเพื่อช่วยนำทาง spec ขนาดใหญ่

ความแตกต่างระหว่าง Spec-First และ Design-First mode คืออะไร?

Spec-First Mode เก็บ spec เป็นไฟล์ใน Git และแก้ไขผ่าน code editor พร้อมการซิงค์ Git แบบสองทาง ส่วน Design-First Mode เก็บ spec ไว้ในโปรเจกต์ Apidog บนคลาวด์และแก้ไขผ่าน UI แบบฟอร์ม เลือก Spec-First หาก workflow ของทีมทำงานบน Git อยู่แล้ว

สรุป

เวิร์กโฟลว์ API แบบ Git-native ช่วยให้โค้ดและ API contract อยู่ในระบบเดียวกัน Spec กลายเป็นไฟล์ ไฟล์กลายเป็น commit และ commit ไหลผ่าน review process ที่ทีมใช้อยู่แล้ว

Apidog Spec-First Mode เพิ่ม editor สไตล์ IDE, outline ที่นำทางได้ และการซิงค์ Git แบบสองทาง คุณแก้ไข YAML หรือ JSON ดิบ, commit ด้วยข้อความที่ชัดเจน, push แล้วตรวจสอบสถานะ "Synced just now."

ลองใช้ Spec-First Mode และนำ API spec ของคุณกลับสู่ Git.

DEV Community