โค้ดของคุณอยู่ใน Git. CI pipeline, การรีวิว, และประวัติการเผยแพร่ของคุณก็อยู่ใน Git. แล้วทำไม API spec ของคุณถึงต้องไปอยู่ในที่อื่น?
เวิร์กโฟลว์ API ที่เป็นแบบ Git-native จะเก็บ OpenAPI definition ของคุณไว้ในที่เดียวกับโค้ดของคุณ คุณแก้ไข spec เป็นไฟล์ YAML หรือ JSON ธรรมดา, commit, และ push ผ่านกระบวนการรีวิวเดียวกับที่คุณใช้สำหรับสิ่งอื่น ๆ ไม่มีฐานข้อมูลคลาวด์แยกต่างหาก ไม่ต้องยุ่งยากกับการ export-import. Spec ก็เป็นเพียงอีกไฟล์หนึ่งใน repo ของคุณ.
เวิร์กโฟลว์ API แบบ Git-native หมายถึงอะไร
เวิร์กโฟลว์ API แบบ Git-native ถือว่า API spec ของคุณเป็นโค้ด. ไฟล์ OpenAPI อยู่ใน repository ควบคู่ไปกับบริการของคุณ. ทุกการเปลี่ยนแปลงคือ commit. ทุก commit มีผู้เขียน, ข้อความ, และ diff.
สิ่งนี้ให้สามสิ่งที่คุณคาดหวังจากซอร์สโค้ดอยู่แล้ว:
- ประวัติเวอร์ชัน. คุณสามารถดูได้ว่าใครเปลี่ยน endpoint เมื่อไหร่.
git blameใช้ได้กับ spec ของคุณ. - การสร้าง branch และการรีวิว. การเปลี่ยนแปลง Spec จะผ่าน pull request. ผู้รีวิวจะเห็น diff ที่แน่นอนก่อนที่จะมีการรวม (merge) ใดๆ.
- แหล่งความจริงเดียว. ไฟล์ใน
mainคือสัญญา (contract). เครื่องมือ, เอกสาร, และ mock ทั้งหมดอ่านจากไฟล์นี้.
นี่คือแนวคิดหลักเบื้องหลังเวิร์กโฟลว์ API แบบ spec-first: การกำหนดสเปคเป็นผู้นำ และการนำไปใช้เป็นผู้ตาม. สำหรับข้อมูลเชิงลึกเพิ่มเติมเกี่ยวกับแนวปฏิบัตินั้น โปรดดูคู่มือของเราเกี่ยวกับ การพัฒนา API แบบ spec-first.
แนวทางตรงกันข้ามคือการเก็บ spec ของคุณไว้ในแอปพลิเคชันคลาวด์ที่เป็นกรรมสิทธิ์. ซึ่งใช้ได้จนกว่าทีมของคุณจะเติบโตขึ้นหรือกระบวนการของคุณเป็นผู้ใหญ่มากขึ้น. แล้วปัญหาจะเริ่มปรากฏ.
ปัญหาของ API spec ที่ถูกล็อคไว้กับคลาวด์
เครื่องมือออกแบบ API ส่วนใหญ่เก็บ spec ไว้ในฐานข้อมูลของตนเอง. คุณแก้ไขผ่าน UI ของพวกเขา. "ไฟล์" ที่คุณคิดว่าคุณเป็นเจ้าของจริง ๆ แล้วเป็นเพียงแถวหนึ่งในระบบของผู้อื่น.
สิ่งนี้ทำให้เกิดปัญหาในลักษณะที่คาดการณ์ได้.
การรีวิวเกิดขึ้นในสองที่. การเปลี่ยนแปลงโค้ดผ่าน GitHub. การเปลี่ยนแปลง Spec ผ่านเครื่องมือแยกต่างหากที่มีความคิดเห็นและประวัติของตัวเอง. ผู้รีวิวต้องสลับบริบท. การอนุมัติก็อาจไม่ตรงกัน.
Diff ถูกซ่อนไว้. เมื่อ spec อยู่ในฐานข้อมูลคลาวด์ คุณจะไม่สามารถเห็น diff แบบบรรทัดต่อบรรทัดที่ชัดเจนใน pull request ของคุณได้. คุณอนุมัติ "v3 ของการออกแบบ" โดยไม่รู้ว่ามีอะไรเปลี่ยนแปลงไปจริง ๆ.
การส่งออกกลายเป็นเรื่องยุ่งยาก. ในการนำ spec เข้าสู่ CI คุณต้องส่งออก, commit ไฟล์ที่ส่งออก, และหวังว่าไม่มีใครแก้ไขสำเนาในคลาวด์ในระหว่างนั้น. สองแหล่งความจริง, ความขัดแย้งที่หลีกเลี่ยงไม่ได้.
การทำงานอัตโนมัติก็เป็นปัญหา. 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 อยู่แล้ว. คุณออกแบบ API เป็นไฟล์ YAML หรือ JSON ดิบ, และ Apidog จะซิงค์ไฟล์เหล่านั้นกับ Git repo ของคุณทั้งสองทาง.
นี่คือสิ่งที่คุณจะได้รับ.
editor OpenAPI สไตล์ IDE
คุณเขียน spec ใน code editor ไม่ใช่ในรูปแบบฟอร์ม. editor นี้มอบความสะดวกสบายที่คุณคาดหวังจาก IDE:
- การเน้นไวยากรณ์ (Syntax highlighting) สำหรับ YAML และ JSON.
- การตรวจสอบความถูกต้องตาม OpenAPI และ Swagger schemas, เพื่อให้ข้อผิดพลาดปรากฏขึ้นขณะที่คุณพิมพ์.
- การเติมข้อความอัตโนมัติ (Auto-completion) สำหรับคำสำคัญ (keywords), ประเภท (types), และการอ้างอิง (references) ของ OpenAPI.
คุณยังคงควบคุมไฟล์ที่แน่นอน. ไม่มีฟิลด์ที่ซ่อนอยู่, ไม่มีเมตาดาตาที่แสดงเฉพาะใน UI.
ไฟล์ YAML/JSON ดิบ
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.
โครงร่างที่สามารถนำทางได้ซึ่งถูกแยกวิเคราะห์โดยอัตโนมัติ
ขณะที่คุณพิมพ์, Apidog จะแยกวิเคราะห์ไฟล์และสร้างโครงร่างภาพในแถบด้านข้างซ้าย. Paths, operations, และ schemas จะปรากฏเป็นโครงสร้างต้นไม้ที่คุณสามารถคลิกผ่านได้. คุณจะได้รับความสามารถในการอ่านของเครื่องมือออกแบบและความแม่นยำของไฟล์ดิบในเวลาเดียวกัน.
Spec ที่ยาวก็ยังสามารถนำทางได้. กระโดดไปยัง endpoint ได้โดยไม่ต้องเลื่อนดูหลายร้อยบรรทัด.
การซิงค์ Git แบบสองทาง
Spec-First Mode เชื่อมต่อกับ Git provider ของคุณและซิงค์การเปลี่ยนแปลงทั้งสองทิศทาง. รองรับ GitHub และ GitLab โดยตรง, และ Azure DevOps ผ่าน Git Connection.
ดึงการเปลี่ยนแปลงที่เพื่อนร่วมทีมของคุณ push เข้ามา. แก้ไขในเครื่องใน Apidog editor. จากนั้น commit และ push กลับไปยัง branch เดิม. Repo และ workspace ของคุณจะยังคงสอดคล้องกัน.
Commit, push, และตัวบ่งชี้สถานะการซิงค์
คุณไม่จำเป็นต้องออกจาก Apidog เพื่อจัดการ Git. จัดเตรียมการเปลี่ยนแปลงของคุณ, เขียนข้อความ commit, และ push. ตัวบ่งชี้สถานะการซิงค์จะบอกคุณว่าสถานะปัจจุบันเป็นอย่างไร. หลังจากการ push สำเร็จ, มันจะแสดงข้อความว่า "Synced just now." หากคุณเปลี่ยนใจก่อนที่จะ push, คุณสามารถทิ้งการแก้ไขที่ยังไม่ได้ push และกลับสู่สถานะที่ซิงค์ล่าสุดได้.
การซิงค์แบบสองทางนี้เป็นหัวใจของเวิร์กโฟลว์ API แบบ Git-native. สำหรับคำแนะนำโดยละเอียดเกี่ยวกับการทำงานกับ GitHub โปรดดู ซิงค์ OpenAPI spec ไปยัง GitHub.
คำแนะนำการตั้งค่า
นี่คือวิธีการเปลี่ยนจาก repo ที่ว่างเปล่าไปเป็น spec ที่ซิงค์แล้ว. ข้อมูลอ้างอิงฉบับเต็มอยู่ใน เอกสาร Spec-First Mode.
- สร้างโปรเจกต์จาก repo. ใน Apidog, เริ่มต้นโปรเจกต์ Spec-First ใหม่และเชื่อมต่อ Git provider ของคุณ. เลือก repository ที่เก็บ API spec ของคุณและเลือก branch ที่ต้องการติดตาม, โดยปกติคือ
main. Apidog จะดึงไฟล์ spec ที่มีอยู่เข้ามาใน editor.
- แก้ไข spec. เปิดไฟล์ OpenAPI ใน editor. เพิ่ม endpoint, ปรับ schema, หรือแก้ไข response. การเน้นไวยากรณ์, การตรวจสอบความถูกต้อง, และการเติมข้อความอัตโนมัติจะช่วยแนะนำคุณขณะที่คุณเขียน. โครงร่างในแถบด้านข้างซ้ายจะอัปเดตเมื่อไฟล์มีการเปลี่ยนแปลง.
- ติดตามไฟล์ที่ถูกแก้ไข, เพิ่ม, และลบ. Apidog จะแสดงไฟล์ที่คุณเปลี่ยนแปลงไปตั้งแต่การซิงค์ครั้งล่าสุด. ไฟล์ที่ถูกแก้ไข, เพิ่ม, และลบจะถูกทำเครื่องหมายไว้เพื่อให้คุณรู้ว่ามีอะไรบ้างที่จะถูกรวมเข้าไปใน commit.
- เขียนข้อความ commit. อธิบายการเปลี่ยนแปลงด้วยภาษาที่เข้าใจง่าย, เช่นเดียวกับที่คุณทำใน Git client ทั่วไป. "Add 404 response to getOrder" ดีกว่า "update spec."
- Push. ส่ง commit ไปยัง branch ที่ติดตาม. เพื่อนร่วมทีมของคุณและ CI pipeline ของคุณจะเห็นเวอร์ชันใหม่นี้.
- ตรวจสอบ "Synced just now." ดูตัวบ่งชี้สถานะการซิงค์เพื่อยืนยันการ push. เมื่อมันแสดง "Synced just now," การแก้ไขในเครื่องของคุณและ remote branch จะตรงกัน. จากจุดนี้, การเปลี่ยนแปลงจะไหลผ่านกระบวนการ pull request และการรีวิวตามปกติของคุณ.
นั่นคือขั้นตอนทั้งหมด: pull, edit, commit, push, verify. ไม่มีขั้นตอนการส่งออก. ไม่มีแหล่งความจริงที่สอง.
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 เป็นหลัก | ทีมที่ชอบเวิร์กโฟลว์แบบภาพ |
ไม่มีโหมดใด "ดีกว่า" กัน. มันรองรับพฤติกรรมการทำงานที่แตกต่างกัน. หากกระบวนการรีวิวและการเผยแพร่ของคุณทำงานบน Git อยู่แล้ว, Spec-First Mode จะช่วยลดความซับซ้อน. หากทีมของคุณออกแบบด้วยภาพและไม่ค่อยได้แตะ OpenAPI ดิบ, Design-First Mode อาจเหมาะสมกว่า.
ควรใช้เมื่อใด
เลือกใช้ Spec-First Mode เมื่อ:
- Spec ของคุณควรผ่าน pull request และ code review.
- คุณต้องการ
git blameและประวัติ commit ที่แท้จริงบน API contract ของคุณ. - CI ของคุณรัน spec linting, contract tests, หรือ code generation ที่ต้องการไฟล์บนดิสก์.
- วิศวกรหลายคนแก้ไข spec และคุณต้องการ diff ที่สะอาดและสามารถ merge ได้.
- คุณเบื่อกับการส่งออกจากเครื่องมือหนึ่งไปป้อนให้เครื่องมืออื่น.
ยึดติดกับแนวทางแบบภาพและ cloud-first เมื่อทีมของคุณออกแบบ API โดยไม่ได้เขียน OpenAPI ดิบ, หรือเมื่อผู้ที่ไม่ใช่วิศวกรเป็นเจ้าของ spec และชอบ editor ที่เป็นแบบฟอร์ม.
คำถามที่พบบ่อย (FAQ)
เวิร์กโฟลว์ API แบบ Git-native คืออะไร?
เวิร์กโฟลว์ API แบบ Git-native จะเก็บ OpenAPI spec ของคุณเป็นไฟล์ใน Git repository และจัดการทุกการเปลี่ยนแปลงผ่าน commits, branches, และ pull requests. Spec จะเป็นไปตามกระบวนการรีวิวและการควบคุมเวอร์ชันเดียวกับโค้ดแอปพลิเคชันของคุณ, ดังนั้นจึงมีแหล่งความจริงเดียว.
Apidog Spec-First Mode รองรับ GitHub และ GitLab หรือไม่?
ใช่. Spec-First Mode ซิงค์แบบสองทางกับ GitHub และ GitLab โดยตรง. Azure DevOps ได้รับการสนับสนุนผ่าน Git Connection. คุณเชื่อมต่อ repo, เลือก branch, และ Apidog จะรักษาการแก้ไขของคุณและ remote ให้ซิงค์กัน.
ฉันสามารถแก้ไขไฟล์ OpenAPI เป็น YAML หรือ JSON ดิบได้หรือไม่?
ใช่. Spec-First Mode มี editor สไตล์ IDE สำหรับ YAML และ JSON ดิบ, พร้อมการเน้นไวยากรณ์, การตรวจสอบความถูกต้องของ schema, และการเติมข้อความอัตโนมัติสำหรับ OpenAPI และ Swagger. โครงร่างในแถบด้านข้างซ้ายจะแยกวิเคราะห์ไฟล์โดยอัตโนมัติเพื่อให้คุณสามารถนำทาง spec ขนาดใหญ่ได้อย่างรวดเร็ว.
ความแตกต่างระหว่าง Spec-First และ Design-First mode คืออะไร?
Spec-First Mode เก็บ spec ของคุณเป็นไฟล์ใน Git และแก้ไขใน code editor พร้อมการซิงค์แบบสองทาง. Design-First Mode เก็บ spec ไว้ในโปรเจกต์ Apidog บนคลาวด์พร้อม editor ที่เป็นแบบฟอร์มที่มองเห็นได้. เลือก Spec-First หากเวิร์กโฟลว์ของคุณทำงานบน Git อยู่แล้ว.
สรุป
เวิร์กโฟลว์ API แบบ Git-native จะยุติการแยกส่วนระหว่างโค้ดและ API contract ของคุณ. Spec จะกลายเป็นไฟล์, ไฟล์จะกลายเป็น commit, และ commit จะไหลผ่านกระบวนการรีวิวที่คุณไว้วางใจอยู่แล้ว.
Apidog Spec-First Mode มอบ editor สไตล์ IDE, โครงร่างที่สามารถนำทางได้, และการซิงค์ Git แบบสองทางเพื่อให้สิ่งนั้นเป็นจริง. คุณแก้ไข YAML หรือ JSON ดิบ, commit ด้วยข้อความที่ชัดเจน, push, และดูสถานะแสดงว่า "Synced just now."
ลองใช้ Spec-First Mode และนำ API spec ของคุณกลับสู่ Git.