Thanawat Wongchai

Posted on Jun 3 • Originally published at apidog.com

Apidog โหมด Spec-First คืออะไร

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

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

คู่มือนี้สรุปวิธีใช้งาน Apidog Spec-First Mode แบบ implementation-focused: โหมดนี้คืออะไร, ต่างจาก Design-First อย่างไร, วิธีตั้งค่า, เวิร์กโฟลว์ประจำวัน, ข้อจำกัดของเบต้า และคำถามที่พบบ่อย หากต้องการเข้าใจแนวคิดภาพรวมของ Git-native API workflow อ่านเพิ่มเติมได้ที่ เวิร์กโฟลว์ API ที่ทำงานร่วมกับ Git ได้อย่างเป็นธรรมชาติ

Apidog Spec-First Mode คืออะไร?

โหมด Spec-First คือโหมดแก้ไขเวอร์ชันเบต้าใน Apidog ที่ให้คุณจัดการ API design ผ่านเอกสาร OpenAPI ดิบโดยตรง คุณเปิดไฟล์ YAML หรือ JSON, แก้ไข, ตรวจสอบความถูกต้อง, คอมมิต และพุชกลับไปยัง Git

การซิงค์เป็นแบบสองทาง:

เมื่อเพื่อนร่วมทีมพุชการเปลี่ยนแปลงเข้า repo คุณดึงเข้ามาใน Apidog ได้
เมื่อคุณแก้ spec ใน Apidog คุณคอมมิตและพุชกลับไปยัง repo ได้
Git กลายเป็น source of truth สำหรับประวัติ, review, branching และ collaboration

โหมดนี้เหมาะกับทีมที่ใช้ Git เป็นหลักอยู่แล้ว เช่น backend engineers, platform teams และบริษัทที่ออกแบบ API ผ่าน pull request ไฟล์ spec จะอยู่ใน workflow เดียวกับ codebase อื่น ๆ ของทีม

ต่างจากเครื่องมือ API ที่ซ่อน spec ไว้หลัง UI แบบฟอร์ม โหมด Spec-First เปิดไฟล์จริงให้คุณแก้โดยตรง

โหมด Spec-First เทียบกับ Design-First

Apidog มี 2 โหมดหลัก:

Design-First Mode: แก้ API ผ่าน visual form และ UI panel
Spec-First Mode: แก้ OpenAPI YAML/JSON โดยตรงใน code editor

อ่านการเปรียบเทียบเชิงลึกได้ที่ การเปรียบเทียบระหว่าง spec-first กับ design-first

แง่มุม	Design-First Mode	Spec-First Mode (เบต้า)
Editor หลัก	Visual form และ UI panel	Raw YAML/JSON code editor
Source of truth	ฐานข้อมูลโปรเจกต์ Apidog	ไฟล์ spec ใน Git repo
Git sync	อิงจาก export/import	ซิงค์สองทางแบบ native
เหมาะกับ	ทีมผสม, ผู้ใช้ที่ชอบ UI	ทีมวิศวกรรมที่ใช้ Git เป็นหลัก
Learning curve	ง่ายและมีคำแนะนำ	เหมาะกับผู้ที่รู้จัก OpenAPI

ไม่มีโหมดใด “ดีกว่า” โดยสมบูรณ์ ให้เลือกตามวิธีทำงานของทีม คุณสามารถสลับระหว่างสองโหมดได้จากโมดูล APIs

คุณสมบัติสำคัญ

Spec-First Mode รวม editor, navigator, Git integration และ team controls ไว้ใน workflow เดียว

1. แก้ OpenAPI ด้วย editor สไตล์ IDE

พื้นที่หลักคือ code editor สำหรับเอกสาร OpenAPI คุณสามารถแก้ YAML หรือ JSON ได้โดยตรง

ความสามารถที่ช่วยตอนแก้ spec:

Syntax highlighting สำหรับ key, value และโครงสร้างของ OpenAPI
Schema validation ตามข้อกำหนด OpenAPI
Autocomplete สำหรับ OpenAPI และ Swagger
แจ้งข้อผิดพลาดเมื่อ response object, schema หรือ required field ไม่ถูกต้อง

ตัวอย่าง endpoint ที่คุณแก้ใน editor:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Autocomplete มีประโยชน์มากเมื่อแก้ schema ลึก ๆ เช่น ตอนเลือกว่าจะใช้ additionalProperties, $ref, required, format หรือ field อื่นตาม OpenAPI spec

2. นำทางไฟล์ spec ผ่าน outline อัตโนมัติ

ไฟล์ openapi.yaml ของ API จริงอาจยาวหลายพันบรรทัด Spec-First Mode จึงสร้าง outline ทางซ้ายจากไฟล์โดยอัตโนมัติ

Outline จะแยกโครงสร้าง เช่น:

paths
operations เช่น GET /users/{userId}
components
schemas
reusable objects อื่น ๆ

เมื่อคลิก node ใน outline editor จะกระโดดไปยังตำแหน่งนั้นทันที คุณจึงนำทางด้วยความหมายของ API แทนการไล่หาบรรทัด เช่น ไปที่ POST /orders แทนการเลื่อนไปบรรทัดที่ 1,847

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

นี่คือแกนหลักของ Spec-First Mode คุณเชื่อม Apidog กับ Git repo แล้วซิงค์ spec ทั้งสองทิศทาง

รองรับโดยตรง:

GitHub
GitLab

สำหรับ Azure DevOps ใช้ผ่าน Generic Git Connection ด้วยข้อมูลประจำตัว Git มาตรฐาน

ผู้ให้บริการ	วิธีเชื่อมต่อ
GitHub	Direct integration
GitLab	Direct integration
Azure DevOps	Generic Git Connection

หลังเชื่อมต่อแล้ว:

Pull เพื่อดึงการเปลี่ยนแปลงล่าสุดจาก repo
แก้ spec ใน Apidog
Commit การเปลี่ยนแปลง
Push กลับไปยัง branch ที่เชื่อมต่อ

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

4. Commit, push และ sync status

Spec-First Mode ใช้ mental model แบบ Git ที่นักพัฒนาคุ้นเคย:

แก้ไฟล์
ตรวจสอบการเปลี่ยนแปลง
เขียน commit message
Commit
Push ไปยัง repo

ตัวบ่งชี้สถานะการซิงค์ช่วยให้รู้ว่า spec ใน Apidog ตรงกับ repo หรือไม่ เช่นสถานะ “Synced just now” หมายความว่าไฟล์ในพื้นที่ทำงานตรงกับ Git repo แล้ว

สิ่งนี้ลดปัญหา spec ล้าสมัย เพราะคุณเห็นได้ทันทีว่ายังมีการเปลี่ยนแปลงที่ไม่ได้พุชอยู่หรือไม่

5. ติดตามการเปลี่ยนแปลงก่อน commit

ก่อน commit คุณตรวจสอบไฟล์ที่เปลี่ยนได้เหมือนดู git status

Spec-First Mode จะแสดงว่าไฟล์ใด:

ถูกแก้ไข
ถูกเพิ่ม
ถูกลบ

ขั้นตอนที่ควรทำก่อน commit:

เปิดรายการ changed files
ตรวจสอบว่าแก้เฉพาะสิ่งที่ต้องการ
ทิ้งการเปลี่ยนแปลงที่ไม่ต้องการ
เขียน commit message ให้ชัดเจน
Commit และ push

วิธีนี้ช่วยให้ Git history สะอาด และป้องกันการพุชการทดลองที่ยังไม่พร้อมเข้า repo หลัก

6. ผูกโปรเจกต์กับ repo และ branch

โปรเจกต์ Spec-First ถูกสร้างจาก repository และ branch ที่ระบุ เช่น main

นั่นหมายความว่าโปรเจกต์จะอ้างอิงตำแหน่งจริงใน Git เสมอ:

spec มาจาก repo ที่กำหนด
branch ที่แก้ไขชัดเจน
history อยู่ใน Git
review ทำผ่าน workflow ของทีมได้

ระหว่างตั้งค่า คุณยังกำหนดสิทธิ์ทีมได้ว่าใครเข้าถึงโปรเจกต์และแก้ไขอะไรได้บ้าง

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

ขั้นตอนเต็มอยู่ในเอกสาร: docs.apidog.com/spec-first-mode-beta-2058268m0

ทำตามลำดับนี้:

สลับโหมด
- เปิดโมดูล APIs ใน Apidog
- ไปที่สวิตช์โหมดมุมล่างซ้าย
- เปลี่ยนจาก Design-First เป็น Spec-First Mode
เชื่อมต่อ Git provider
- ใช้ direct integration สำหรับ GitHub หรือ GitLab
- ใช้ Generic Git Connection สำหรับ Azure DevOps
สร้างโปรเจกต์จาก repository
- เลือก repo ที่มี openapi.yaml หรือ openapi.json
- เลือก branch เช่น main
- Apidog จะผูกโปรเจกต์กับ repo และ branch นั้น
กำหนดสิทธิ์ทีม
- เลือกสมาชิกที่เข้าถึงโปรเจกต์ได้
- กำหนดสิทธิ์การแก้ไขตาม workflow ของทีม
แก้ spec
- เปิดไฟล์ OpenAPI ใน editor
- ใช้ outline เพื่อนำทาง
- ใช้ validation และ autocomplete ระหว่างเขียน
ตรวจสอบ changed files
- ดูว่าไฟล์ใดถูกแก้
- ทิ้งการเปลี่ยนแปลงที่ไม่ต้องการ
Commit
- เขียน commit message ที่สื่อความหมาย เช่น Add POST /invoices endpoint
Push
- Push commit ไปยัง branch ที่เชื่อมต่อ
ตรวจสอบ sync status
- เมื่อเห็น “Synced just now” แสดงว่า spec ใน Apidog และ repo ตรงกันแล้ว

สรุป flow คือ:

Switch mode -> Connect Git -> Create project -> Edit spec -> Review changes -> Commit -> Push -> Verify sync

ตัวอย่างเวิร์กโฟลว์ประจำวัน

เมื่อเริ่มวันทำงาน:

Pull การเปลี่ยนแปลงล่าสุดจาก branch ที่เชื่อมต่อ
เปิด outline แล้วไปที่ endpoint ที่ต้องแก้
แก้ YAML หรือ JSON ใน editor
ใช้ autocomplete เพื่อช่วยเขียน field ตาม OpenAPI
ใช้ validation เพื่อตรวจ $ref, schema และ required fields
ตรวจ changed files
Commit ด้วยข้อความที่ชัดเจน
Push ไปยัง repo
ให้ทีม review ผ่าน pull request ตาม workflow ปกติ

ตัวอย่าง schema ที่อาจเพิ่มระหว่างทำงาน:

components:
  schemas:
    Invoice:
      type: object
      required: [id, amount, currency]
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: integer
          description: Amount in the smallest currency unit
        currency:
          type: string
          example: USD
        status:
          type: string
          enum: [draft, sent, paid]

ตัวอย่าง commit message:

Add Invoice schema

หรือถ้าเพิ่ม endpoint:

Add POST /invoices endpoint

หลักการคือ treat spec as code: review ได้, diff ได้, commit ได้, rollback ได้ และ version control ได้เหมือน source code อื่น

ใครควรใช้ Spec-First Mode?

ใช้ Spec-First Mode หากทีมของคุณ:

ใช้ Git เป็นหลักอยู่แล้ว
review API contract ผ่าน pull request
ต้องการ version spec ควบคู่กับ service code
มี backend/platform engineers ที่คุ้นเคยกับ YAML หรือ JSON
ต้องการให้ OpenAPI spec เป็น source of truth
ต้องการ workflow แบบ commit/push แทน export/import

เลือก Design-First Mode แทน หากทีมของคุณ:

ต้องการ UI แบบ visual form
มี product, design หรือ non-engineer ร่วมออกแบบ API
ต้องการ guided experience มากกว่าแก้ YAML โดยตรง
ไม่อยากจัดการ OpenAPI syntax เอง

หากยังตัดสินใจไม่ได้ อ่าน โพสต์เปรียบเทียบ เพื่อเลือกโหมดให้ตรงกับทีม

ข้อจำกัดและหมายเหตุของเวอร์ชันเบต้า

Spec-First Mode ยังเป็นเบต้า ดังนั้นควรตั้งความคาดหวังให้เหมาะสม:

ความสามารถและพฤติกรรมอาจเปลี่ยนแปลงได้
Direct integration รองรับ GitHub และ GitLab
Azure DevOps ใช้ผ่าน Generic Git Connection
หากทีมมี Git provider หรือ workflow เฉพาะ ควรทดสอบก่อนใช้กับโปรเจกต์สำคัญ
ควรเริ่มจาก repo ที่ไม่ critical ก่อนนำไปใช้กับ main branch จริง

เพราะโหมดนี้ซิงค์กับ Git repo จริง คุณยังต้องใช้วินัย Git ตามปกติ:

Commit เฉพาะสิ่งที่ตั้งใจ
ตรวจ diff ก่อน commit
Push เมื่อพร้อม
ทิ้งการเปลี่ยนแปลงที่ไม่ควรเผยแพร่
หลีกเลี่ยงการพุชการทดลองเข้า branch หลักโดยไม่ review

ข้อดีของเบต้าคือ feedback ของผู้ใช้ยังมีผลต่อทิศทางของฟีเจอร์ หาก workflow ของคุณมีจุดที่ยังติดขัด ควรรายงานเพื่อช่วยปรับปรุงโหมดนี้

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

Spec-First Mode ใช้งานฟรีหรือไม่?

Spec-First Mode เป็นฟีเจอร์เบต้าใน Apidog การเข้าถึงขึ้นอยู่กับแผน Apidog และสถานะเบต้า วิธีตรวจสอบที่ตรงที่สุดคือเปิดโมดูล APIs แล้วดูว่าสามารถสลับไปใช้ Spec-First Mode ได้หรือไม่ในบัญชีของคุณ

รองรับ Git provider ใดบ้าง?

รองรับ direct integration สำหรับ GitHub และ GitLab ส่วน Azure DevOps ใช้ผ่าน Generic Git Connection ด้วยข้อมูลประจำตัว Git มาตรฐาน โฮสต์ Git อื่นอาจใช้งานได้ผ่านการเชื่อมต่อทั่วไปนี้ เพราะอิงกับ Git มาตรฐานแทน provider-specific API

สลับกลับไปใช้ Design-First Mode ได้หรือไม่?

ได้ คุณสามารถสลับระหว่าง Spec-First และ Design-First ได้จากสวิตช์โหมดมุมล่างซ้ายของโมดูล APIs

แก้ไฟล์ฟอร์แมตใดได้บ้าง?

คุณแก้เอกสาร OpenAPI ได้ในรูปแบบ YAML หรือ JSON editor รองรับ syntax highlighting, schema validation และ autocomplete สำหรับ OpenAPI และ Swagger

เกิดอะไรขึ้นกับการแก้ไขที่ยังไม่ได้ push?

การแก้ไขที่ยังไม่ได้ push จะยังไม่เข้า Git repo ที่ใช้ร่วมกัน Spec-First Mode จะแสดงสถานะว่ามีไฟล์ใดถูกแก้, เพิ่ม หรือลบ หากไม่ต้องการเผยแพร่การเปลี่ยนแปลงนั้น ให้ทิ้งก่อน push

บทสรุป

Apidog Spec-First Mode รวม OpenAPI editor และ Git workflow ไว้ในที่เดียว คุณแก้ YAML หรือ JSON โดยตรง, นำทางผ่าน outline, ตรวจ validation ระหว่างเขียน และซิงค์สองทางกับ GitHub, GitLab หรือ Azure DevOps ผ่าน Generic Git Connection

โหมดนี้เหมาะกับทีมที่ใช้ Git เป็นหลักและต้องการ treat API spec as code หากทีมของคุณ review API contract ผ่าน pull request อยู่แล้ว ให้ลองเริ่มจาก repo ทดสอบ: เปิด Spec-First Mode, เชื่อม repository, แก้ spec เล็ก ๆ, commit, push แล้วตรวจ sync status

เมื่อพร้อม อ่านเอกสารและลองใช้งานได้ที่ ลองใช้โหมด Spec-First ในเอกสารประกอบ

DEV Community