Thanawat Wongchai

Posted on Jul 14 • Originally published at apidog.com

สุดยอดเครื่องมือ CLI น้ำหนักเบา สำหรับออกแบบ API

เครื่องมือออกแบบ API หลายตัวมีขนาดใหญ่เกินกว่างานที่ต้องทำจริง หากคุณต้องการเพียงตรวจสอบกฎการตั้งชื่อ รวมไฟล์สเปกที่แยกกัน หรือตรวจจับการเปลี่ยนชื่อฟิลด์ที่อาจทำให้ไคลเอนต์พัง คุณควรทำได้จากเทอร์มินัลด้วยคำสั่งเดียวและการตั้งค่าน้อยที่สุด

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

บทความนี้รวบรวม CLI สำหรับงานออกแบบ API ที่ติดตั้งเร็ว เริ่มใช้ได้ทันที และนำไปต่อกับ CI ได้ง่าย โดยเน้นเครื่องมือที่ทำงานเฉพาะด้านได้ดี: lint สเปก, bundle ไฟล์ OpenAPI, สร้าง SDK และเอกสาร, ตรวจจับ breaking changes และออกแบบ Endpoint หรือ Schema จากเทอร์มินัล หากต้องการภาพรวมของกระบวนการออกแบบก่อนเลือกเครื่องมือ โปรดอ่าน วิธีการออกแบบ API

เครื่องมือทั้งหมดใช้ OpenAPI Specification เป็นภาษากลาง จึงสามารถต่อเป็น Pipeline เดียวกันได้ เช่น ออกแบบ → export → lint → bundle → ตรวจ breaking changes → generate SDK

อะไรทำให้ CLI เหมาะกับการออกแบบ API

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

ติดตั้งและเริ่มต้นเร็ว

ใช้ไบนารีเดียว หรือรันผ่าน npx ได้โดยไม่ต้องติดตั้งแบบ global เหมาะกับ container ใหม่และ CI runner
ให้ผลลัพธ์ได้ทันทีโดยแทบไม่ต้องตั้งค่า

ชี้คำสั่งไปที่ไฟล์ OpenAPI แล้วเห็นปัญหาหรือได้ไฟล์ผลลัพธ์ทันที จากนั้นจึงค่อยเพิ่มกฎเฉพาะทีม
เขียนสคริปต์และทำงานใน CI ได้

มี exit code ที่ชัดเจน มีผลลัพธ์แบบ structured หรือค้นหาด้วย grep ได้ และไม่ต้องพึ่ง GUI

ตัวอย่าง Pipeline ขั้นต่ำใน Pull Request:

# 1) ตรวจสอบรูปแบบและโครงสร้าง
spectral lint openapi.yaml

# 2) รวมไฟล์ $ref ให้เป็นสเปกเดียว
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# 3) ป้องกัน breaking changes
oasdiff breaking main-openapi.yaml dist/openapi.yaml

Redocly CLI: lint และ bundle โดยไม่ต้องติดตั้ง

Redocly CLI เป็นจุดเริ่มต้นที่รวดเร็วสำหรับการตรวจสอบและรวม OpenAPI เพราะรันผ่าน npx ได้ทันที ใช้ลิขสิทธิ์ MIT และเหมาะกับงานสองประเภท:

ตรวจสอบสเปกด้วย lint
รวมสเปกหลายไฟล์ที่ใช้ $ref ด้วย bundle

npx @redocly/cli@latest lint openapi.yaml
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

ใช้ bundle เมื่อทีมแยกสเปกตาม resource หรือ domain เช่น:

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── components/
    ├── schemas.yaml
    └── responses.yaml

ผลลัพธ์ที่ bundle แล้วจะเป็นไฟล์เดียว ซึ่งนำไปใช้กับ mock server, documentation site, SDK generator และเครื่องมือ diff ได้ง่ายขึ้น การแยกไฟล์ลักษณะนี้ยังช่วยลด merge conflict และเหมาะกับ เวิร์กโฟลว์การออกแบบ API แบบ Git-native

ดีที่สุดสำหรับ: รวมสเปกหลายไฟล์และตรวจสอบความถูกต้องอย่างรวดเร็ว

ข้อจำกัด: กฎ lint เริ่มต้นเหมาะกับการตรวจสอบพื้นฐาน หากต้องบังคับ style guide ของทีมอย่างละเอียด ให้ใช้ Spectral เพิ่มเติม

Spectral: บังคับใช้ API style guide เป็นโค้ด

Spectral จาก Stoplight เป็น linter โอเพนซอร์สภายใต้ลิขสิทธิ์ Apache-2.0 รองรับ OpenAPI 3.x, OpenAPI 2.0, AsyncAPI และ Arazzo

ติดตั้งและรัน:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

แม้ยังไม่มีไฟล์ config Spectral ก็ใช้ ruleset oas ที่มีมาให้เพื่อตรวจจับปัญหาพื้นฐาน เช่น คำอธิบายที่หายไป ตัวอย่างที่ไม่ถูกต้อง และโครงสร้างสเปกที่ผิด

เมื่อทีมต้องการบังคับมาตรฐานร่วมกัน ให้เพิ่มไฟล์ .spectral.yaml:

extends:
  - spectral:oas

rules:
  require-operation-id:
    description: ทุก operation ต้องมี operationId
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

จากนั้นรันคำสั่งเดิม:

spectral lint openapi.yaml

กฎที่นำไปใช้จริงมักรวมถึง:

ทุก endpoint ต้องมี operationId
path ต้องใช้รูปแบบ kebab-case
ทุก response error ต้องอ้างอิง schema กลาง
ทุก endpoint ต้องมี description และตัวอย่าง request/response

แนวทางนี้ช่วยเปลี่ยน style guide ให้ตรวจสอบได้อัตโนมัติ และสอดคล้องกับ หลักการออกแบบ API

ดีที่สุดสำหรับ: บังคับใช้มาตรฐาน API ของทีมใน local และ CI

ข้อจำกัด: ตรวจได้ทีละสเปก ไม่ได้เปรียบเทียบระหว่างเวอร์ชัน จึงควรใช้ร่วมกับ oasdiff

oasdiff: ตรวจจับ breaking changes ด้วยไบนารีเดียว

linter บอกได้ว่าสเปกปัจจุบันถูกต้องหรือไม่ แต่ไม่ได้บอกว่าการเปลี่ยนแปลงจากเวอร์ชันก่อนทำให้ไคลเอนต์เดิมพังหรือเปล่า

oasdiff แก้ปัญหานี้โดยเปรียบเทียบ OpenAPI สองเวอร์ชัน เครื่องมือเป็น Go binary เดียว ใช้ลิขสิทธิ์ Apache-2.0 และติดตั้งได้ด้วย go install, Homebrew หรือ binary ที่คอมไพล์ไว้แล้ว

go install github.com/oasdiff/oasdiff@latest

oasdiff breaking old-openapi.yaml new-openapi.yaml

คำสั่งสำคัญ:

# แสดงเฉพาะ breaking changes
oasdiff breaking old-openapi.yaml new-openapi.yaml

# สร้าง changelog ที่มนุษย์อ่านง่าย
oasdiff changelog old-openapi.yaml new-openapi.yaml

# แสดง diff รายละเอียด
oasdiff diff old-openapi.yaml new-openapi.yaml

เพิ่มเข้า CI เพื่อให้ Pull Request ล้มเหลวเมื่อมี breaking change:

oasdiff breaking main-openapi.yaml openapi.yaml

ตัวอย่างการเปลี่ยนแปลงที่มักถูกตรวจจับ:

ลบ endpoint เดิม
ลบ response code ที่เคยรองรับ
เปลี่ยนชนิดข้อมูลของ field
ทำให้ field เดิมกลายเป็น required
จำกัด enum หรือ validation ที่ไคลเอนต์เดิมอาจไม่ผ่าน

ดีที่สุดสำหรับ: ป้องกัน breaking changes ใน Pull Request โดยตั้งค่าน้อยมาก

ข้อจำกัด: ความแม่นยำขึ้นอยู่กับว่าสเปก OpenAPI ตรงกับ API ที่ deploy จริงหรือไม่ และไม่ได้ตรวจ style guide

Optic: lint และ diff ใน CLI เดียว พร้อมข้อควรระวัง

Optic เป็นเครื่องมือ MIT ที่รวมการตรวจสอบและเปรียบเทียบความต่างของ OpenAPI ไว้ใน CLI เดียว

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

อย่างไรก็ตาม repository สาธารณะของ Optic ถูกเก็บถาวรในเดือนมกราคม 2026 และโครงการไม่ได้รับการบำรุงรักษาต่อ แม้ซอร์สโค้ด MIT อาจยังใช้งานได้ แต่จะไม่มีการอัปเดตกฎหรือ security fix ใหม่

หากกำลังเริ่ม Pipeline ใหม่ ให้เลือก oasdiff สำหรับตรวจ breaking changes และใช้ Spectral สำหรับ lint แทน

ดีที่สุดสำหรับ: ทีมที่มี Pipeline เดิมซึ่งใช้ Optic อยู่แล้ว

ข้อจำกัด: ไม่ได้รับการบำรุงรักษาตั้งแต่ต้นปี 2026 ควรวางแผนย้ายไปใช้เครื่องมืออื่น

openapi-generator: สร้าง SDK, server stub และเอกสารจากสเปก

openapi-generator ใช้ลิขสิทธิ์ Apache-2.0 และสร้าง client SDKs, server stubs และเอกสารจาก OpenAPI ได้หลายภาษา

ติดตั้ง CLI wrapper:

npm install -g @openapitools/openapi-generator-cli

สร้าง TypeScript client ที่ใช้ Axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client

เปลี่ยนค่า -g เพื่อเลือกภาษาและ generator ที่ต้องการ:

openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g kotlin -o ./client-kotlin

รัน generator ใน CI ทุกครั้งที่ OpenAPI เปลี่ยน เพื่อป้องกัน SDK หรือเอกสารหลุดจาก API contract แนวทางนี้คือแก่นของ การพัฒนา API แบบ Design-First

ดีที่สุดสำหรับ: สร้าง SDK, server stub และเอกสารให้ตรงกับสเปก

ข้อจำกัด: ต้องใช้ JDK 11 หรือใหม่กว่า และโค้ดที่สร้างขึ้นมักเป็นจุดเริ่มต้นที่ต้องปรับให้เข้ากับโปรเจกต์

Apidog CLI: ออกแบบ Endpoint และ Schema จากเทอร์มินัล

ห้าเครื่องมือก่อนหน้าช่วยตรวจสอบหรือแปลงสเปกที่มีอยู่แล้ว ส่วน Apidog ช่วยในขั้นก่อนหน้า คือออกแบบ Endpoint และ Schema แล้ว export เป็น OpenAPI

ส่วนที่เป็น CLI คือ apidog-cli ซึ่งติดตั้งจาก npm ได้:

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog schema list
apidog export --format openapi -o openapi.yaml

กลุ่มคำสั่งที่ใช้ได้ครอบคลุม:

endpoint
schema
security-scheme
folder
mock
import
export

ตัวอย่างลำดับงาน:

# ตรวจสอบ Endpoint และ Schema ที่ออกแบบไว้
apidog endpoint list
apidog schema list

# Export เพื่อนำเข้าสู่ Pipeline OpenAPI
apidog export --format openapi -o openapi.yaml

# ตรวจ style และโครงสร้าง
spectral lint openapi.yaml

# ตรวจ breaking changes เทียบกับเวอร์ชันหลัก
oasdiff breaking main-openapi.yaml openapi.yaml

CLI ส่งผลลัพธ์แบบ JSON ที่มี agentHints.nextSteps จึงต่อเข้ากับสคริปต์หรือ agent workflow ได้ง่าย ดูรายละเอียดคำสั่งทั้งหมดได้ใน คู่มือ Apidog CLI ฉบับเต็ม

Apidog ไม่ได้เป็น OpenAPI linter และไม่ใช่เครื่องมือบังคับ style guide งานเหล่านั้นยังเหมาะกับ Spectral และ Redocly มากกว่า นอกจากนี้ Apidog ไม่ใช่โอเพนซอร์ส แต่เป็นผลิตภัณฑ์เชิงพาณิชย์ที่มี Free Tier

ดีที่สุดสำหรับ: ออกแบบ Endpoint และ Schema จากจุดเดียว แล้ว export OpenAPI เข้าสู่ Pipeline

ข้อจำกัด: ไม่ใช่ linter และไม่ใช่โอเพนซอร์ส จึงควรใช้เป็นส่วนเสริมของเครื่องมือตรวจสอบ

วิธีเลือกเครื่องมือ

โดยทั่วไปไม่จำเป็นต้องเลือกเพียงตัวเดียว ให้จับคู่เครื่องมือกับขั้นตอนของงาน

เครื่องมือ	เหมาะสำหรับ	การติดตั้ง	โอเพนซอร์สหรือไม่	หมายเหตุ
Redocly CLI	Bundle สเปก + lint เบื้องต้น	`npx @redocly/cli@latest`	ใช่ (MIT)	ไม่ต้องติดตั้ง เหมาะกับสเปกหลายไฟล์
Spectral	ตรวจ style guide	`npm i -g @stoplight/spectral-cli`	ใช่ (Apache-2.0)	ใช้ ruleset เริ่มต้นหรือเขียนกฎเองได้
oasdiff	ตรวจ breaking changes	`go install github.com/oasdiff/oasdiff@latest`	ใช่ (Apache-2.0)	Go binary เดียว และยังได้รับการบำรุงรักษา
Optic	lint + diff ในเครื่องมือเดียว	`npm i -g @useoptic/optic`	ใช่ (MIT)	ถูกเก็บถาวรใน ม.ค. 2026
openapi-generator	สร้าง SDK, stub และเอกสาร	`npm i -g @openapitools/openapi-generator-cli`	ใช่ (Apache-2.0)	ต้องใช้ JDK 11+
Apidog CLI	ออกแบบ Endpoint + export สเปก	`npm i -g apidog-cli`	ไม่ (มี Free Tier)	ไม่ใช่ linter

ชุดเครื่องมือที่ใช้งานได้จริงสำหรับทีมส่วนใหญ่:

# 1. ออกแบบและ export OpenAPI
apidog export --format openapi -o openapi.yaml

# 2. ตรวจมาตรฐาน API
spectral lint openapi.yaml

# 3. Bundle หากแยกสเปกไว้หลายไฟล์
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# 4. ป้องกัน breaking changes
oasdiff breaking main-openapi.yaml dist/openapi.yaml

# 5. สร้าง SDK เมื่อจำเป็น
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client

หากต้องการดูเครื่องมือที่ครอบคลุมมากกว่า CLI โปรดดู ทางเลือก Swagger สำหรับการออกแบบและทดสอบ API และ วิธีการออกแบบ REST API

สรุป

CLI แบบ Lightweight ช่วยให้ API design workflow ทำงานในเครื่องและ CI ด้วยคำสั่งชุดเดียวกัน:

Redocly CLI สำหรับ bundle และ lint เบื้องต้น
Spectral สำหรับบังคับใช้ style guide
oasdiff สำหรับป้องกัน breaking changes
openapi-generator สำหรับสร้าง SDK, stub และเอกสาร
Apidog CLI สำหรับออกแบบ Endpoint และ Schema ก่อน export OpenAPI
Optic สำหรับ Pipeline เก่าที่ควรเตรียมย้ายออก

แนวทางที่ใช้งานได้จริงคือให้ OpenAPI เป็น source of truth แล้วรัน lint, bundle, diff และ generate ทุกครั้งที่มีการ push

หากต้องการออกแบบ Endpoint และ Schema จากจุดเดียวก่อนส่ง OpenAPI เข้า Pipeline นี้ ให้ดาวน์โหลด Apidog และลองใช้ apidog-cli โดยใช้มันเป็นขั้นตอนออกแบบก่อนเครื่องมือตรวจสอบ ไม่ใช่สิ่งทดแทน linter ของคุณ