เครื่องมือ CLI โอเพนซอร์ส ฟรี สำหรับการออกแบบ API

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

บทความนี้เกี่ยวกับเครื่องมือโอเพนซอร์สของชุดเครื่องมือดังกล่าว ทุกเครื่องมือในที่นี้เป็นแบบเปิดเผยซอร์สภายใต้ใบอนุญาตแบบอนุญาต (permissive license) ใช้งานได้ฟรีโดยไม่มีค่าใช้จ่ายต่อที่นั่ง (seat cost) และคุณสามารถโฮสต์เองหรือปักหมุดเวอร์ชันที่คุณควบคุมได้ สิ่งนี้สำคัญเมื่อการออกแบบ API ของคุณอยู่ใน Git repo และคุณต้องการให้การตรวจสอบทำงานเหมือนกันในทุกแล็ปท็อปและทุกไปป์ไลน์ หากคุณต้องการภาพรวมที่กว้างขึ้นว่าสิ่งเหล่านี้ทำงานร่วมกันอย่างไร ให้เริ่มต้นด้วยคู่มือของเราเกี่ยวกับ วิธีการออกแบบ API จากนั้นกลับมาที่นี่เพื่อเลือก CLI

คุณจะได้รับเครื่องมือหกอย่าง แต่ละอย่างมีคำสั่งติดตั้งจริงและคำสั่งเดียวที่แสดงการทำงาน: ตัวตรวจสอบสไตล์ (linter) สำหรับกฎสไตล์, ตัวเลือกที่รวดเร็วโดยใช้ Go ซึ่งเป็นทางเลือก, ตัวรวมโค้ดที่ตรวจสอบความถูกต้องด้วย, ตัวสร้างโค้ดและเอกสาร, และสองเครื่องมือสำหรับจับการเปลี่ยนแปลงที่ส่งผลกระทบระหว่างเวอร์ชันของสเปก OpenAPI Specification เป็นภาษาทั่วไปที่เครื่องมือทั้งหมดใช้ ดังนั้นสเปกที่คุณตรวจสอบด้วยเครื่องมือหนึ่งจะสามารถส่งต่อไปยังเครื่องมือถัดไปได้อย่างราบรื่น

ข้อควรทราบอย่างตรงไปตรงมาในเบื้องต้น Apidog ได้รับการกล่าวถึงที่นี่ แต่ไม่ใช่โอเพนซอร์ส เป็นผลิตภัณฑ์เชิงพาณิชย์ที่มีบริการฟรี (free tier) และไม่ได้ตรวจสอบสไตล์สเปกของคุณ ดังนั้นจึงเป็นส่วนเสริมที่ถูกต้อง ไม่ใช่รายการโอเพนซอร์ส เครื่องมือด้านล่างนี้คือชุดเครื่องมือออกแบบโอเพนซอร์สที่แท้จริง

อะไรที่ทำให้เครื่องมือ CLI เป็นโอเพนซอร์สสำหรับการออกแบบ API

โอเพนซอร์สคือคำกล่าวอ้างที่เฉพาะเจาะจง ไม่ใช่แค่ความรู้สึก สำหรับรายการนี้ เครื่องมือจะมีคุณสมบัติเมื่อมีคุณสมบัติสามประการจริง

ประการแรก ใบอนุญาต จะต้องเป็นใบอนุญาตที่อนุญาตอย่างแท้จริง (permissive) หรือใบอนุญาตแบบ copyleft ที่คุณสามารถอ่านได้; MIT และ Apache-2.0 เป็นสองใบอนุญาตที่คุณจะเห็นบ่อยที่สุดที่นี่ นั่นคือสิ่งที่ทำให้คุณสามารถใช้เครื่องมือในโครงการเชิงพาณิชย์ได้โดยไม่มีค่าธรรมเนียมใบอนุญาตหรือการนับจำนวนที่นั่ง

ประการที่สอง การโฮสต์เองและการควบคุมเวอร์ชัน คุณสามารถจัดหาไบนารี (vendor the binary) ปักหมุดเวอร์ชันที่แน่นอน และรันแบบออฟไลน์ทั้งหมดใน CI runner ที่แยกจากเครือข่ายได้ เครื่องมือในที่นี้ไม่มีการ "โทรกลับบ้าน" หรือต้องการบัญชีเพื่อทำงานหลักของมัน

ประการที่สาม การบำรุงรักษาและชุมชน Repository ที่มีการ commit ล่าสุด, ปัญหาที่เปิดอยู่ซึ่งได้รับการตอบสนอง, และ changelog สาธารณะ โครงการที่ถูกทิ้งร้างอาจยังคงเป็น MIT-licensed และยังคงเป็นการลงทุนที่ไม่ดี ดังนั้นฉันจะระบุสถานะการบำรุงรักษาในจุดที่สำคัญ

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

Spectral: ตัวตรวจสอบสไตล์ OpenAPI ที่ยืดหยุ่น

Spectral จาก Stoplight คือตัวตรวจสอบสไตล์โอเพนซอร์สอ้างอิงสำหรับคำอธิบาย API ภายใต้ใบอนุญาต Apache-2.0 มันอ่านชุดกฎ (ไฟล์ YAML, JSON, หรือ JavaScript ที่ระบุรายการกฎของคุณ) และนำไปใช้กับเอกสาร OpenAPI 3.x, OpenAPI 2.0, AsyncAPI และ Arazzo หากทีมของคุณมีคู่มือสไตล์ API ที่เขียนไว้ Spectral คือวิธีการที่คุณจะทำให้มันสามารถทำงานได้

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

เมื่อติดตั้ง มันมาพร้อมกับชุดกฎ oas ที่จะแจ้งเตือนคำอธิบายที่ขาดหายไป, ตัวอย่างที่ไม่ถูกต้อง, และปัญหาโครงสร้าง คุณค่าที่แท้จริงจะปรากฏในการกำหนดกฎเอง: กำหนดให้มี operationId ในทุกการทำงาน, สคีมาที่ใช้ร่วมกันในการตอบสนองข้อผิดพลาด, ข้อกำหนดการตั้งชื่อบนเส้นทาง (paths) กฎเหล่านี้อยู่ใน repo ของคุณและทำงานเหมือนกันสำหรับผู้ร่วมงานทุกคน

ดีที่สุดสำหรับ: การบังคับใช้คู่มือสไตล์ของทีมในรูปแบบโค้ด ข้อจำกัดที่ตรงไปตรงมา: Spectral ตรวจสอบสเปกเดียวเท่านั้น ไม่สามารถเปรียบเทียบสองเวอร์ชันได้ ดังนั้นจึงควรใช้ร่วมกับเครื่องมือเปรียบเทียบ (diff tool) เพื่อตรวจจับการเปลี่ยนแปลงที่ส่งผลกระทบ

vacuum: ตัวตรวจสอบสไตล์ที่เร็วที่สุด, ใช้แทน Spectral rulesets ได้

หาก Spectral เป็นมาตรฐาน vacuum คือตัวเลือกที่เน้นความเร็ว เป็นตัวตรวจสอบสไตล์ Go ที่ได้รับอนุญาต MIT ซึ่งเข้ากันได้ 100% กับ Spectral rulesets ดังนั้นคุณสามารถชี้ไปที่ชุดกฎเดียวกันกับที่คุณเขียนไว้แล้วและได้ผลลัพธ์กลับมาเร็วกว่ามากสำหรับสเปกขนาดใหญ่ ซึ่งเป็นสิ่งที่คุณต้องการอย่างแท้จริงในการใช้เป็น pre-commit hook หรือใน CI loop ที่รวดเร็ว

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml

แฟล็ก -d ให้เอาต์พุตโดยละเอียดตามกฎแต่ละข้อ vacuum ยังทำได้มากกว่าการตรวจสอบสไตล์อีกด้วย มันสร้างรายงาน HTML และเอกสารจากสเปกเดียวกัน เนื่องจากเป็นไบนารีที่คอมไพล์แล้วตัวเดียวโดยไม่มี Node runtime จึงเริ่มต้นได้อย่างรวดเร็วและสามารถใส่ลงในคอนเทนเนอร์ได้อย่างราบรื่น

ดีที่สุดสำหรับ: การตรวจสอบสไตล์สเปกขนาดใหญ่ได้อย่างรวดเร็วด้วยชุดกฎที่คุณมีอยู่แล้ว ข้อจำกัดที่ตรงไปตรงมา: ระบบนิเวศของชุดกฎและเอกสารยังคงมุ่งเน้นไปที่ Spectral ดังนั้นคุณมักจะเขียนกฎตามโมเดลของ Spectral และรันผ่าน vacuum นี่เป็นคุณสมบัติหนึ่ง แต่หมายความว่า Spectral ยังคงเป็นสิ่งที่คุณเรียนรู้ก่อน

Redocly CLI: ตรวจสอบสไตล์และรวม (bundle) ในไบนารีเดียว

Redocly CLI ได้รับอนุญาต MIT และครอบคลุมงานที่แตกต่างออกไปเล็กน้อย มันตรวจสอบสไตล์ แต่จุดเด่นคือ bundle: มันนำสเปกที่แบ่งออกเป็นหลายไฟล์ $ref (วิธีที่สมเหตุสมผลในการรักษางานออกแบบ API ขนาดใหญ่ให้ดูแลรักษาง่าย) และรวมให้เป็นเอกสารเดียวสำหรับเครื่องมือที่คาดหวังไฟล์เดียว นอกจากนี้ยังสร้างเอกสารอ้างอิง API จากผลลัพธ์ที่รวมแล้ว

npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml

การแบ่งสเปกของคุณออกเป็นไฟล์ตามทรัพยากรช่วยให้ diff อ่านง่ายและลดความขัดแย้งในการผสาน (merge conflicts) ซึ่งเป็นหัวใจสำคัญของ เวิร์กโฟลว์การออกแบบ API ที่เน้น Git คำสั่ง bundle ของ Redocly คือขั้นตอนที่เปลี่ยนแหล่งที่มาแบบหลายไฟล์กลับไปเป็นอาร์ติแฟกต์เดียวที่ CI, mock server หรือเว็บไซต์เอกสารของคุณใช้

ดีที่สุดสำหรับ: โครงการสเปกหลายไฟล์ที่ต้องการการรวม (bundling) และการตรวจสอบความถูกต้อง ข้อจำกัดที่ตรงไปตรงมา: กฎการตรวจสอบสไตล์เริ่มต้นของมันเบากว่าชุดกฎ Spectral ที่ปรับแต่งเองได้เต็มที่ ดังนั้นหลายทีมจึงใช้ Redocly สำหรับการรวม และ Spectral หรือ vacuum สำหรับการบังคับใช้สไตล์อย่างละเอียด

openapi-generator: เปลี่ยนการออกแบบให้เป็นไคลเอนต์, สตับ, และเอกสาร

การออกแบบยังไม่เสร็จสมบูรณ์จนกว่าคนอื่นจะสามารถสร้างต่อได้ openapi-generator ได้รับอนุญาต Apache-2.0 และสร้าง SDK ของไคลเอนต์, สตับของเซิร์ฟเวอร์, และเอกสารจากสเปก OpenAPI ในหลายสิบภาษา การถือว่าสเปกเป็นแหล่งที่มาของความจริงและสร้างส่วนที่เหลือคืองานหลักของแนวทาง schema-first, contract-driven ซึ่งเราครอบคลุมใน หลักการออกแบบ API

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

สลับ -g typescript-axios เป็น go, python, java, kotlin หรือเครื่องมือสร้างอื่น ๆ ที่รองรับมากมาย รันใน CI ทุกครั้งที่มีการเปลี่ยนแปลงสเปก และไลบรารีไคลเอนต์ของคุณจะไม่เบี่ยงเบนไปจากสัญญา

ดีที่สุดสำหรับ: การรักษาโค้ดและเอกสารที่สร้างขึ้นให้สอดคล้องกับการออกแบบ ข้อจำกัดที่ตรงไปตรงมา: ต้องใช้ JDK ในการรัน (JDK 11+), โค้ดที่สร้างขึ้นเป็นจุดเริ่มต้นที่คุณมักจะปรับแต่ง และคุณภาพของเครื่องมือสร้างแตกต่างกันไปตามภาษาเป้าหมาย ตรวจสอบผลลัพธ์ก่อนที่คุณจะจัดส่ง

oasdiff: ตรวจจับการเปลี่ยนแปลงที่ส่งผลกระทบก่อนที่จะไปถึงไคลเอนต์

ตัวตรวจสอบสไตล์จะบอกคุณว่าสเปกหนึ่งสะอาดหรือไม่ ไม่สามารถบอกคุณได้ว่าการเปลี่ยนชื่อฟิลด์ทำให้ไคลเอนต์ทุกตัวในระบบโปรดักชันพัง oasdiff คือเครื่องมือ Go ที่ได้รับอนุญาต Apache-2.0 ที่เติมเต็มช่องว่างนี้: ให้สเปกสองเวอร์ชันและมันจะรายงานความแตกต่าง และโดยเฉพาะการเปลี่ยนแปลงที่ส่งผลกระทบ

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml

คำสั่ง breaking จะแสดงเฉพาะการเปลี่ยนแปลงที่ทำให้ผู้ใช้ที่มีอยู่เสียหาย; changelog ให้รายการที่มนุษย์อ่านได้ของทุกสิ่งที่เปลี่ยนแปลง ไม่ว่าจะส่งผลกระทบหรือไม่; diff ให้การเปลี่ยนแปลงทั้งหมดที่เครื่องอ่านได้ เชื่อมต่อ oasdiff breaking เข้ากับการตรวจสอบ pull-request และการเปลี่ยนแปลงที่ส่งผลกระทบจะกลายเป็น build ที่ล้มเหลว แทนที่จะเป็นการแจ้งเตือนตอนตี 3

ดีที่สุดสำหรับ: การป้องกันการเปลี่ยนแปลงที่ส่งผลกระทบใน CI ข้อจำกัดที่ตรงไปตรงมา: มันเปรียบเทียบสเปก ดังนั้นจึงดีเท่ากับวินัยของคุณในการรักษาสเปกให้ทันสมัยกับ API จริง มันไม่ได้ตรวจสอบสไตล์; ใช้ร่วมกับ Spectral หรือ vacuum

Optic: เปรียบเทียบและตรวจสอบสไตล์พร้อมกัน, พร้อมข้อควรระวังเรื่องการบำรุงรักษา

Optic ได้รับอนุญาต MIT และทำในสิ่งที่เครื่องมืออื่นแยกกัน: มันตรวจสอบสไตล์และเปรียบเทียบ OpenAPI ในเครื่องมือเดียว โดยเปรียบเทียบสองเวอร์ชันเพื่อแจ้งเตือนการเปลี่ยนแปลงที่ส่งผลกระทบในขณะเดียวกันก็ใช้กฎสไตล์ด้วย นอกจากนี้ยังสามารถสร้างสเปกจากการสังเกตการจราจรทดสอบได้อีกด้วย

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

นี่คือความจริงที่รายการโอเพนซอร์สควรบอกคุณ: Repository สาธารณะของ Optic ถูกเก็บถาวรในช่วงต้นปี 2026 และโครงการนี้ไม่ได้รับการบำรุงรักษาอย่างกระตือรือร้นอีกต่อไป ซอร์สโค้ด MIT ยังคงทำงานได้ ดังนั้นคุณสามารถนำไปใช้เองได้ แต่คุณจะไม่ได้รับกฎใหม่หรือแพตช์ความปลอดภัย สำหรับการตรวจจับการเปลี่ยนแปลงที่ส่งผลกระทบในปัจจุบัน oasdiff เป็นตัวเลือกที่ได้รับการบำรุงรักษา; Optic ยังคงอยู่ในรายการเพราะคุณจะยังคงพบเห็นมันในไปป์ไลน์ที่มีอยู่

ดีที่สุดสำหรับ: ทีมที่ลงทุนไปแล้ว หรือใครก็ตามที่ต้องการตรวจสอบสไตล์และเปรียบเทียบใน CLI เดียว ข้อจำกัดที่ตรงไปตรงมา: ไม่ได้รับการบำรุงรักษาแล้วตั้งแต่ต้นปี 2026; ถือว่าเป็นของเก่าและวางแผนเส้นทางการย้ายข้อมูล

Apidog อยู่ตรงไหน (และไม่อยู่ตรงไหน)

Apidog ไม่ใช่โอเพนซอร์ส และไม่ได้ตรวจสอบ OpenAPI ของคุณหรือบังคับใช้กฎสไตล์; Spectral, vacuum และ Redocly คือเครื่องมือตรวจสอบสไตล์ของคุณ จุดสิ้นสุด Apidog นำเสนอการแลกเปลี่ยนที่แตกต่างกัน: แทนที่จะต่อไบนารีหกตัวแยกกันเข้าด้วยกัน บริการฟรี (free tier) ของมันบวกกับไบนารี apidog-cli ให้คุณมีพื้นที่รวมสำหรับการออกแบบ endpoint และ schema ข้อมูล จากนั้นส่งออกผลลัพธ์เป็น OpenAPI เพื่อป้อนกลับเข้าสู่การตรวจสอบโอเพนซอร์สเหล่านี้ได้โดยตรง

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml

CLI มีกลุ่มคำสั่งสำหรับ endpoint, schema, mock, และ import/export ดังนั้นคุณสามารถเขียนสคริปต์การออกแบบ API จากเทอร์มินัลและส่งออกสเปกที่ส่งออกไปยัง openapi-generator หรือ oasdiff ได้ ดู คู่มือ Apidog CLI ฉบับสมบูรณ์ สำหรับชุดคำสั่งทั้งหมด ข้อเท็จจริงที่ตรงไปตรงมา: Apidog เป็นตัวเลือกเชิงพาณิชย์แบบบูรณาการที่ทำงานร่วมกับชุดเครื่องมือโอเพนซอร์สได้ดี ไม่ใช่สิ่งทดแทนสำหรับเครื่องมือตรวจสอบสไตล์และไม่ใช่โครงการโอเพนซอร์สด้วยตัวมันเอง

วิธีการเลือก

เลือกเครื่องมือให้ตรงกับงาน ทีมส่วนใหญ่ใช้เครื่องมือเหล่านี้สองหรือสามอย่างร่วมกัน ไม่ใช่เพียงอย่างเดียว

ชุดเครื่องมือที่ใช้งานได้จริง: Spectral หรือ vacuum สำหรับสไตล์, Redocly สำหรับการรวม (bundling), oasdiff สำหรับการเปลี่ยนแปลงที่ส่งผลกระทบ, และ openapi-generator เพื่อสร้างไคลเอนต์ หากการบำรุงรักษาเครื่องมือจำนวนมากนั้นมากเกินไปสำหรับคุณ แพลตฟอร์มแบบรวม (integrated platform) จะครอบคลุมส่วนการออกแบบและการส่งออกในที่เดียว สำหรับภาพรวมที่กว้างขึ้นของภูมิทัศน์เครื่องมือนอกเหนือจาก CLI โปรดดูคู่มือของเราเกี่ยวกับ ทางเลือก Swagger สำหรับการออกแบบและการทดสอบ API และพื้นฐานใน วิธีการออกแบบ REST API

สรุป

ชุดเครื่องมือ CLI โอเพนซอร์สสำหรับการออกแบบ API นั้นเป็นผู้ใหญ่และใช้งานได้ฟรี: Spectral และ vacuum ตรวจสอบสไตล์, Redocly รวมโค้ด, openapi-generator สร้างไคลเอนต์, และ oasdiff ป้องกันการเปลี่ยนแปลงที่ส่งผลกระทบ โดยมี Optic เป็นตัวเลือกเก่าที่ควรรับรู้ เชื่อมโยงสิ่งเหล่านี้เข้ากับ CI และสัญญา API ของคุณจะได้รับการตรวจสอบทุกครั้งที่ push โดยไม่มีค่าใช้จ่ายต่อที่นั่ง (per-seat cost) และไม่มีการผูกขาดผู้ขาย (vendor lock-in)

หากคุณต้องการออกแบบ endpoint และ schema ในเครื่องมือเดียวแบบรวม และส่งออก OpenAPI ที่สะอาดเข้าสู่ไปป์ไลน์เดียวกันนั้น ดาวน์โหลด Apidog และลองใช้ apidog-cli; เป็นคู่หูเชิงพาณิชย์สำหรับชุดเครื่องมือโอเพนซอร์ส ไม่ใช่สิ่งทดแทนสำหรับเครื่องมือตรวจสอบสไตล์ของคุณ ไม่ว่าจะด้วยวิธีใด เป้าหมายก็เหมือนกัน: ตรวจจับปัญหาการออกแบบในเทอร์มินัล ก่อนที่จะไปถึงผู้ใช้งานของคุณ