ในทุกทีม API ที่ผมเคยทำงานด้วย มักมีสองแนวทาง: ทีมหนึ่งเขียน OpenAPI spec ด้วยมือแล้วเก็บไว้ใน specs/ โดยให้ Git เป็นแหล่งความจริง อีกทีมใช้เครื่องมือออกแบบแบบภาพ สร้าง endpoint ผ่าน UI แล้ว export spec เมื่อ CI แจ้งเตือนว่ามีอะไรไม่ตรงกัน
ผมเคยอยู่ทั้งสองแบบ แนวทางแรกช้ากว่าในวันแรก แต่เร็วกว่าในวันที่เก้าสิบ แนวทางที่สองตรงกันข้าม และจนถึงประมาณหนึ่งเดือนก่อน เครื่องมือออกแบบ API ที่ผมใช้บ่อยที่สุดอย่าง Apidog รองรับแนวทางที่สองเป็นหลัก: UI ดีมาก แต่การส่ง YAML ไปกลับระหว่างเครื่องมือกับ Git ยังเป็นสิ่งที่ต้องคอยป้องกันในการ review code
ช่วงกลางเดือนเมษายน Spec-First Mode (Beta) ปรากฏในกล่อง New Project ผมไม่ได้เขียนถึงทันที เพราะอยากลองกับโปรเจกต์จริงก่อน และรอให้ปัญหาช่วงแรกมีโอกาสโผล่ขึ้นมา หลังจากลองกับ OpenAPI spec ของโปรเจกต์ส่วนตัว นี่คือสิ่งที่ผมจะบอกทีมก่อนให้ลองใช้
Spec-First Mode เปลี่ยนอะไร
สั้น ๆ: Apidog ตอนนี้มีสองโหมดโปรเจกต์ที่ทำงานต่างกันจริง
General Mode คือโหมดเดิมที่หลายคนคุ้นเคย:
- คลิก + New Project
- สร้าง endpoint ผ่านฟอร์มและโครงสร้างโฟลเดอร์
- Apidog สร้าง OpenAPI spec ให้เบื้องหลัง
โหมดนี้เหมาะกับทีมที่ยังไม่อยากแตะ YAML โดยตรง
Spec-First Mode เปลี่ยนจุดศูนย์กลางจาก UI เป็นไฟล์ spec:
- แก้ไขไฟล์
.yamlและ.jsonโดยตรง - ซิงค์สองทางกับ Git repository
- มี syntax highlighting
- มี autocomplete ตาม OpenAPI schema
- มี Real-time Directory Parsing เพื่อสร้าง outline ของ endpoint ใน sidebar ระหว่างที่พิมพ์
ตัวอย่าง spec ที่คุณแก้ในโหมดนี้คือไฟล์จริงใน repo ไม่ใช่ข้อมูลที่ถูก export จากการคลิกใน UI:
openapi: 3.0.3
info:
title: Store API
version: 1.0.0
paths:
/store/token:
post:
summary: Create store token
responses:
"200":
description: Token created
จุดสำคัญคือคุณยังได้ navigation แบบเครื่องมือภาพ แต่ไม่ต้องละทิ้ง Git workflow เดิม คุณเขียน spec เป็นไฟล์ และ Apidog แสดง outline ให้ใช้นำทางทันที
ข้อสรุปของผม: spec-first ไม่ได้แปลว่า “ต้องใช้ text editor เท่านั้น” แต่แปลว่า artifact หลักต้องเป็นไฟล์ใน repository ส่วน UI เป็นมุมมองและเครื่องมือช่วยแก้ไข ไม่ใช่แหล่งความจริงอีกชุดหนึ่ง
ตั้งค่า Spec-First Mode ตั้งแต่ต้นจนจบ
ขั้นตอนที่ผมใช้จริงมี 6 ขั้นตอน ใช้เวลาน้อยกว่าสิบนาที โดยเวลาส่วนใหญ่หมดไปกับการอนุญาต Git
1. สร้างโปรเจกต์ในโหมดที่ถูกต้อง
ไปที่หน้าจอโปรเจกต์ แล้วเลือก:
+ New Project → General → Spec-first Mode
จุดที่ควรระวังคือ General Mode มีป้าย “Recommended” ทำให้หลายคนอาจคลิกผ่านโดยไม่เห็นตัวเลือก Spec-first Mode ด้านข้าง ถ้าต้องการให้ Git เป็นแหล่งความจริง ต้องเลือกโหมดนี้ตั้งแต่ตอนสร้างโปรเจกต์
2. เชื่อมต่อ Git repository
ในส่วน Connect with Git Repository ให้เชื่อมต่อ provider ที่ใช้ เช่น GitHub จากนั้นเลือก:
- Organization
- Repository
- Main branch
Apidog จะใช้ไฟล์ spec ใน branch นั้นเป็น working copy
3. กำหนดค่าโปรเจกต์
ตั้งค่า:
- Project Name
- สิทธิ์ของทีม
- กด Create
การ sync ครั้งแรกจะดึงไฟล์ .yaml และ .json จาก repository เข้ามาใน workspace ของ Apidog
4. แก้ไข spec เหมือนไฟล์ ไม่ใช่แบบฟอร์ม
เปิดไฟล์ YAML หรือ JSON แล้วแก้ไขโดยตรงใน editor
สิ่งที่ควรลองทันที:
- เพิ่ม path ใหม่
- ดู sidebar ว่า outline อัปเดตหรือไม่
- คลิก endpoint ใน sidebar เพื่อกระโดดไปยังบรรทัดที่เกี่ยวข้อง
ตัวอย่างการเพิ่ม endpoint:
paths:
/admin/auth:
post:
summary: Authenticate admin user
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- password
properties:
email:
type: string
format: email
password:
type: string
responses:
"200":
description: Authenticated
"401":
description: Unauthorized
ถ้าคุณคุ้นกับ VS Code + OpenAPI extension อยู่แล้ว ประสบการณ์จะคล้ายกัน แต่ใน Apidog outline จะผูกกับ navigation ของ workspace โดยตรง
5. Commit และ push
มุมขวาบนให้กด Commit & Push
กล่อง dialog จะมี:
- รายการไฟล์ใน Changes
- ช่อง Commit Message
- ปุ่ม Push
- ปุ่ม Discard all changes
ไม่มี staging area แยกแบบ Git CLI สิ่งที่อยู่ใน Changes จะถูก commit พร้อมกัน เหมาะกับงานแก้ spec ที่มักเป็นชุดการเปลี่ยนแปลงขนาดเล็กและชัดเจน
ตัวอย่าง commit message ที่ใช้ได้จริง:
Add admin authentication endpoint
หรือถ้าใช้ conventional commits:
feat(api): add admin authentication endpoint
6. ตรวจสถานะ sync
ดูมุมล่างซ้ายของ workspace สถานะเช่น Synced just now บอกว่าการเปลี่ยนแปลงใน Apidog และ repository ตรงกันหรือไม่
สิ่งที่ควรใช้เป็นกฎง่าย ๆ:
- ถ้าเป็นสถานะ synced: ไฟล์ใน Apidog และ Git ตรงกัน
- ถ้า local มี change: commit/push ก่อนให้คนอื่นใช้ต่อ
- ถ้า remote มี change: pull เข้ามาก่อนแก้ต่อ
สำหรับทีมที่มีหลายคนแก้ spec พร้อมกัน ตัวบ่งชี้นี้สำคัญกว่าที่คิด เพราะช่วยลดปัญหา “ใครแก้ spec ชุดล่าสุดอยู่ที่ไหน”
สิ่งที่ผมสังเกตหลังลองใช้จริง
มีสามประเด็นที่ควรรู้ก่อนใช้กับทีม
1. Outline อัปเดตเร็วพอที่จะใช้เป็น navigation จริง
ผมเคยใช้ live OpenAPI editor หลายตัวที่ re-parse หลัง save หรือมี delay นานพอให้ไม่อยากพึ่ง sidebar แต่ใน Spec-First Mode ของ Apidog outline อัปเดตระหว่างพิมพ์เร็วพอจนใช้เป็น navigation หลักได้
นี่สำคัญมากสำหรับ spec ขนาดใหญ่ เพราะ YAML ซ่อนโครงสร้างไว้ใน indentation และไฟล์ยาว ๆ การมี outline ที่ sync กับไฟล์ทันทีช่วยให้แก้ endpoint ได้เร็วขึ้นโดยไม่ต้อง search ตลอดเวลา
2. Git integration เป็นสองทางจริง
ผมทดสอบโดยแก้ไฟล์เดียวกันจาก local machine แล้ว push ผ่าน terminal ขณะที่ Apidog เปิดอยู่
ผลคือ Apidog ตรวจพบว่า workspace ตามหลัง remote สถานะ sync เปลี่ยน และสามารถดึงการเปลี่ยนแปลงเข้ามาได้จาก UI
สำหรับทีมที่มีทั้งคนใช้ Vim, VS Code, terminal และ Apidog นี่คือ workflow ที่ใช้งานได้จริง:
git checkout main
git pull
vim openapi.yaml
git add openapi.yaml
git commit -m "Update store token response"
git push
คนที่อยู่ใน Apidog ก็ยังเห็นสถานะของ repository และ sync กลับเข้ามาได้ โดยไฟล์ใน Git ยังเป็นแหล่งความจริงเดียวกัน
3. สลับกลับไปใช้ visual designer ในโปรเจกต์เดียวกันไม่ได้
นี่เป็นข้อจำกัดที่ต้องบอกทีมก่อนเริ่ม
ถ้าสร้างโปรเจกต์เป็น Spec-First Mode โปรเจกต์นั้นจะเป็น spec-first ตั้งแต่ต้นจนจบ ไม่สามารถสลับกลางทางไปเป็น visual designer ในโปรเจกต์เดียวกันได้ เพราะ data model เบื้องหลังต่างกัน
ถ้าทีมต้องใช้ทั้งสองแนวทางกับ spec เดียวกัน วิธีที่ใช้งานได้คือ:
- เก็บ OpenAPI spec ไว้ใน Git repository
- ให้โปรเจกต์ Spec-First ชี้ไปที่ repository นั้น
- ให้ผู้ใช้ visual mode เปิดโปรเจกต์แยกที่ import จากแหล่งเดียวกัน
ไม่ใช่ workflow ที่ไร้รอยต่อ แต่ชัดเจนพอสำหรับทีมที่ต้องการคุม source of truth ใน Git
เหมาะกับทีมแบบไหน
ผมจะใช้โหมดนี้ใน production โดยเฉพาะถ้าทีมมี workflow ที่ถือว่า OpenAPI spec เป็น artifact หลักอยู่แล้ว
Spec-First Mode เหมาะถ้า:
- ทีมเขียน OpenAPI ด้วยมืออยู่แล้ว
- CI รัน lint กับ spec เช่น
spectral lint - มีการ generate client SDK จาก spec
- spec ต้องอยู่ใน Git อยู่แล้ว
- engineer ต้องการเปิด pull request กับไฟล์ YAML
- ทีมมีปัญหากับ workflow แบบ
make exportหรือ export จาก UI ที่ไม่มีใครมั่นใจว่าเป็นเวอร์ชันล่าสุด
ตัวอย่าง CI step ที่เข้ากับแนวทางนี้:
name: Validate OpenAPI
on:
pull_request:
paths:
- "openapi.yaml"
- "specs/**"
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Spectral
run: npm install -g @stoplight/spectral-cli
- name: Lint OpenAPI spec
run: spectral lint openapi.yaml
เมื่อ spec อยู่ใน Git จริง การ review จะตรงไปตรงมา:
paths:
+ /store/token:
+ post:
+ summary: Create store token
ทีมสามารถ comment ใน pull request ได้เหมือน review code ปกติ
ไม่เหมาะกับทีมแบบไหน
Spec-First Mode ไม่ใช่คำตอบสำหรับทุกทีม
ยังไม่เหมาะถ้า:
- ทีมไม่เคยแตะ OpenAPI โดยตรง
- visual designer คือเหตุผลหลักที่ทำให้ non-API specialist มีส่วนร่วมได้
- ต้องการสลับระหว่าง visual mode และ spec-first ในโปรเจกต์เดียวกัน
- contributor ส่วนใหญ่ไม่คุ้นกับ YAML, schema, path object หรือ response object
สำหรับทีมเหล่านี้ General Mode ยังเป็นตัวเลือกที่เหมาะกว่า เพราะลดแรงเสียดทานตอนเริ่มต้นได้มากกว่า
Spec-First Mode แลก onboarding ที่ง่ายขึ้นกับความแม่นยำของ source of truth ถ้าทีมยังไม่พร้อมดูแล spec เป็นไฟล์ การแลกเปลี่ยนนี้อาจไม่คุ้ม
ประเด็นสำคัญ
ก่อนหน้านี้ การทำ API แบบ spec-first มักแปลว่าต้องเลือกระหว่างสองอย่าง:
- ใช้ YAML เป็นหลัก แล้วเสียความสะดวกของ API design platform
- ใช้ visual designer เป็นหลัก แล้วเสีย Git ในฐานะแหล่งความจริง
สิ่งที่น่าสนใจใน Spec-First Mode คือ Apidog ลดการบังคับเลือกแบบนั้นลง ไฟล์ใน repo คือไฟล์ที่แก้ใน editor, outline เป็นมุมมองของไฟล์ ไม่ใช่ state แยก และ Git sync เป็นส่วนหนึ่งของ workflow ไม่ใช่ขั้นตอน export/import ภายหลัง
ถ้าทีมของคุณรอ API platform ที่จริงจังกับ spec-first มากกว่าแค่มีปุ่ม export โหมดนี้ควรอยู่ในรายการที่ต้องลอง
ตอนนี้เบต้าใช้งานได้จากกล่อง New Project เลือก Spec-First Mode ตอนสร้างโปรเจกต์ แล้วชี้ไปที่ repository ที่คุณเชื่อถืออยู่แล้ว การ commit ครั้งแรกใช้เวลาประมาณสิบนาที ส่วนการตัดสินใจว่าจะใช้ต่อหรือไม่ น่าจะใช้เวลาประมาณหนึ่งสัปดาห์