Swagger CLI: ตรวจสอบ, Lint และทดสอบ API Spec จากเทอร์มินัล

ใช้ Swagger CLI เพื่อตรวจสอบและรวม OpenAPI spec ของคุณจากเทอร์มินัล ตรวจสอบโค้ดด้วย Redocly CLI และรันการทดสอบ API จริงใน CI ด้วย apidog-cli

INEZA Felin-Michel

INEZA Felin-Michel

16 June 2026

Swagger CLI: ตรวจสอบ, Lint และทดสอบ API Spec จากเทอร์มินัล

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

คุณเปิดพูลรีเควสต์ เอกสารก็สร้างได้เรียบร้อยดี และสามวันต่อมาเพื่อนร่วมทีมก็มาสะกิดคุณ: เซิร์ฟเวอร์ staging ปฏิเสธทุกคำขอเพราะไฟล์ OpenAPI มี $ref ที่ค้างอยู่ (dangling $ref) ซึ่งชี้ไปยังพาธที่คุณเปลี่ยนชื่อไป สเปกดูถูกต้องใน editor มันแสดงผลใน Swagger UI แต่มันกลับไม่ถูกต้องตามจริง และไม่มีอะไรใน pipeline ของคุณจับได้ก่อนที่จะนำไปใช้งานจริง

นี่แหละคือหน้าที่แท้จริงของเครื่องมือ Swagger command-line: จับสเปกที่เสียก่อนที่มนุษย์จะเจอ คำว่า “swagger cli” มักจะหมายถึง @apidevtools/swagger-cli ซึ่งเป็นแพ็คเกจ npm ขนาดเล็กที่มีสองคำสั่งคือ validate และ bundle ใช้สำหรับตรวจสอบเอกสาร OpenAPI และรวมสเปกหลายไฟล์ให้เป็นไฟล์เดียว มันเป็นเครื่องมือที่มีประโยชน์อย่างแท้จริง และคู่มือนี้จะแสดงวิธีใช้งานอย่างถูกต้อง นอกจากนี้ยังแสดงให้เห็นว่ามันมีข้อจำกัดอย่างไร เพราะการตรวจสอบความถูกต้องของสเปกเป็นเพียงครึ่งแรกของการเชื่อมั่นใน API ส่วนครึ่งหลังคือการส่งคำขอจริงและยืนยันผลลัพธ์ที่ได้กลับมา และนั่นคือที่ที่ตัวรันอย่าง Apidog CLI เข้ามามีบทบาท

button

ดังนั้น นี่คืองานที่ต้องใช้เครื่องมือสองชนิดจริงๆ ขั้นแรก ให้ lint และ bundle สเปกด้วย swagger-cli (หรือเครื่องมือรุ่นต่อยอด) เพื่อให้สัญญา (contract) นั้นสมบูรณ์ จากนั้นให้รันการทดสอบจริงกับ API ที่กำลังทำงานอยู่จาก command line เพื่อให้คุณรู้ว่าการใช้งานจริงนั้นตรงกับสัญญา เราจะครอบคลุมทั้งสองส่วน จะบอกอย่างตรงไปตรงมาว่าเครื่องมือใดทำหน้าที่อะไร และมีคำสั่งให้คุณคัดลอกไปใช้ได้เลย

“swagger cli” จริงๆ แล้วหมายถึงอะไร

ไม่มีไบนารีเดียวที่เป็นทางการชื่อ “swagger” ชื่อนี้หมายถึงเครื่องมือหลายอย่าง และการรู้ว่าคุณหมายถึงตัวไหนจะช่วยลดความสับสนได้มาก

คู่มือนี้เกี่ยวกับงานบน command-line: การตรวจสอบความถูกต้อง (validating), การรวมไฟล์ (bundling), การตรวจสอบรูปแบบโค้ด (linting) และการทดสอบ (testing) หากคุณต้องการสำรวจแพลตฟอร์มการออกแบบและทดสอบในวงกว้างขึ้น การรวบรวมทางเลือกของ Swagger ครอบคลุมในส่วนของ GUI

การติดตั้ง swagger-cli

เครื่องมือนี้มาในรูปแบบแพ็คเกจ npm ติดตั้งแบบ global:

npm install -g @apidevtools/swagger-cli

ยืนยันว่าติดตั้งเรียบร้อยแล้ว:

swagger-cli --version
swagger-cli --help

Node.js เป็น dependency เดียวของระบบ เครื่องหรือ CI image ใดๆ ที่ติดตั้ง Node อยู่แล้วสามารถรันได้ หากคุณไม่อยากติดตั้งแบบ global คุณสามารถเรียกใช้ตามต้องการด้วย npx @apidevtools/swagger-cli ... ซึ่งสะดวกสำหรับ build runner แบบชั่วคราว

สิ่งหนึ่งที่ควรรู้ก่อนที่คุณจะพึ่งพามัน: ผู้ดูแลได้ระบุว่า swagger-cli ถูกยกเลิกแล้ว (deprecated) ไฟล์ README ระบุไว้อย่างชัดเจน โดยอ้างถึงภาระการบำรุงรักษาที่สูงจากฐานผู้ใช้จำนวนมากแต่มีผู้ร่วมพัฒนา (contributor) น้อยราย มันยังคงใช้งานได้ และ pipeline จำนวนมากยังคงรันอยู่ทุกวันนี้ แต่โปรเจกต์ใหม่ๆ ถูกชี้ไปที่ Redocly CLI ในฐานะผู้สืบทอดที่ได้รับการดูแลอย่างต่อเนื่อง เราจะกล่าวถึงการย้ายข้อมูลนี้ในส่วนถัดไป เพื่อให้คุณสามารถตัดสินใจได้อย่างรอบคอบ

การตรวจสอบความถูกต้องของสเปกด้วย swagger-cli

คำสั่งหลักคือ validate ชี้ไปที่ไฟล์สเปกของคุณ:

swagger-cli validate openapi.yaml

หากเอกสารถูกต้อง คุณจะได้รับการยืนยันหนึ่งบรรทัดและ exit code เป็น 0 หากมีบางอย่างผิดปกติ คุณจะได้รับข้อผิดพลาดที่อธิบายปัญหาและ exit code ที่ไม่ใช่ศูนย์ ซึ่งเป็นสิ่งที่คุณต้องการใน pipeline

validate ทำการตรวจสอบสองอย่างภายใต้เบื้องหลัง และคุณสามารถปิดการทำงานอย่างใดอย่างหนึ่งได้:

swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml

--no-schema ข้ามการตรวจสอบความถูกต้องตาม OpenAPI JSON Schema ซึ่งเป็นการตรวจสอบโครงสร้างที่ยืนยันว่าเอกสารของคุณมีรูปร่างที่ถูกต้อง --no-spec ข้ามการตรวจสอบความถูกต้องตามกฎของสเปกเอง ซึ่งเป็นการตรวจสอบความหมาย (semantic check) ที่ตรวจจับสิ่งต่างๆ เช่น operation ID ที่ซ้ำกัน หรือ $ref ที่ชี้ไปที่ใดเลย ส่วนใหญ่แล้วคุณต้องการให้ทั้งสองเปิดใช้งาน ซึ่งเป็นค่าเริ่มต้น แฟล็กเหล่านี้มีไว้สำหรับกรณีที่หายากที่ชั้นหนึ่งกำลังแจ้งบางสิ่งที่คุณมีเหตุผลเจตนาที่จะอนุญาต

สิ่งที่ validate จับได้ดี: YAML ที่มีรูปแบบผิดพลาด, ฟิลด์ที่จำเป็นหายไป, $ref ที่เสีย และข้อผิดพลาดทางโครงสร้างที่ทำให้สเปกไม่สามารถแยกวิเคราะห์ได้ สิ่งที่มันไม่ทำคือการบังคับใช้สไตล์ของทีมคุณ มันจะยอมรับสเปกที่ไม่มี description, การตั้งชื่อที่ไม่สอดคล้องกัน และไม่มีตัวอย่าง เพราะไม่มีสิ่งใดที่ละเมิดกฎของ OpenAPI สำหรับการตรวจสอบรูปแบบดังกล่าวคุณต้องมี linter ซึ่งจะกล่าวถึงในส่วนถัดไป

หากการตรวจสอบความถูกต้องเป็นสิ่งเดียวที่คุณต้องการ คู่มือเชิงลึกเกี่ยวกับ วิธีการตรวจสอบความถูกต้องของสเปก OpenAPI เปรียบเทียบเครื่องมือหลายชนิดและกรณีพิเศษที่ควรรู้

การรวมสเปกหลายไฟล์

สเปกจริงไม่ค่อยอยู่ในไฟล์เดียว คุณแยก schema ออกเป็นไดเรกทอรี components/ อ้างอิงด้วย $ref และทำให้ไฟล์ root อ่านง่าย นั่นเป็นสุขอนามัยที่ดี แต่เครื่องมือปลายน้ำจำนวนมากต้องการเอกสารเดียวที่รวมทุกอย่าง คำสั่ง bundle จะรวมโครงสร้างเข้าด้วยกัน:

swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml

แฟล็กที่ควรรู้:

ความแตกต่างระหว่างการ bundle แบบธรรมดาและ --dereference นั้นสำคัญ การ bundle แบบปกติจะเก็บตัวชี้ $ref ภายในไว้ แต่ดึงไฟล์แยกทั้งหมดมารวมเป็นไฟล์เดียว ทำให้เอกสารสามารถพกพาได้ --dereference จะแก้ไขการอ้างอิงทั้งหมดให้เป็นออบเจกต์ภายใน (inline objects) ซึ่งจะทำให้ไฟล์มีขนาดใหญ่ขึ้น แต่รับประกันว่าผู้ใช้ปลายทางไม่ต้องแก้ไขตัวชี้อีกต่อไป ใช้การ bundle แบบธรรมดาสำหรับการเผยแพร่ และใช้รูปแบบที่ dereferenced เมื่อเครื่องมือบางอย่างร้องขอเท่านั้น

รูปแบบทั่วไปคือการตรวจสอบและรวมไฟล์ในขั้นตอนเดียวเป็นส่วนหนึ่งของการ build:

swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json

สัญลักษณ์ && หมายความว่าการ bundle จะทำงานก็ต่อเมื่อการตรวจสอบความถูกต้องผ่านเท่านั้น ดังนั้นสเปกที่เสียจะไม่สร้าง artifact ของการ build

การรวม swagger-cli เข้ากับ CI

การตรวจสอบความถูกต้องมีค่ามากที่สุดเมื่อรันทุกครั้งที่มีการเปลี่ยนแปลง ไม่ใช่เมื่อมีคนจำได้ว่าต้องทำ เพิ่มเข้าไปใน pipeline ของคุณเป็นด่านตรวจเร็ว นี่คือขั้นตอน GitHub Actions ที่จะทำให้ build ล้มเหลวเมื่อสเปกไม่ถูกต้อง:

name: Validate OpenAPI spec

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'components/**'

jobs:
  validate-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate spec
        run: npx @apidevtools/swagger-cli validate openapi.yaml

เนื่องจาก swagger-cli validate ออกจากโปรแกรมด้วย exit code ที่ไม่ใช่ศูนย์เมื่อสเปกไม่ดี ขั้นตอนนี้จะแสดงเป็นสีแดง และพูลรีเควสต์จะแสดงการตรวจสอบที่ล้มเหลว ไม่จำเป็นต้องมีการกำหนดค่าเพิ่มเติม ตัวกรอง paths ป้องกันไม่ให้งานทำงานเมื่อสเปกไม่ได้เปลี่ยนแปลง ซึ่งช่วยประหยัดเวลา CI ของคุณ

นี่คือด่านควบคุมคุณภาพที่ถูกที่สุดที่คุณสามารถเพิ่มเข้าไปใน repo ของ API ได้ มันใช้เวลาไม่กี่วินาทีและหยุดข้อบกพร่องประเภท "เอกสารโกหก" ไม่ให้ไปถึงผู้ใช้ปลายทาง

เมื่อคุณต้องการการตรวจสอบรูปแบบโค้ด (Linting) ไม่ใช่แค่การตรวจสอบความถูกต้อง (Validation) เท่านั้น

การตรวจสอบความถูกต้องตอบคำถามเดียว: เอกสารนี้เป็นเอกสาร OpenAPI ที่ถูกต้องตามกฎหมายหรือไม่? การตรวจสอบรูปแบบโค้ด (Linting) ตอบคำถามที่ยากกว่า: เอกสาร OpenAPI นี้เป็นเอกสารที่ดีตามมาตรฐานของทีมเราหรือไม่? สองอย่างนี้ไม่เหมือนกัน และ swagger-cli ทำเพียงอย่างแรกเท่านั้น

สมมติว่าแนวทางสไตล์ของคุณกำหนดให้ทุก operation ต้องมี summary, ทุก property ต้องมี description, และทุก path ต้องใช้ kebab-case สเปกสามารถละเมิดทั้งสามข้อและยังคงผ่าน swagger-cli validate ได้ เพราะกฎเหล่านี้ไม่ได้เป็นส่วนหนึ่งของข้อกำหนด OpenAPI Linter ช่วยให้คุณสามารถเข้ารหัสและบังคับใช้กฎเหล่านี้ได้

นี่คือเหตุผลหลักที่ทีมย้ายไปใช้ Redocly CLI ซึ่งเป็นเครื่องมือรุ่นต่อยอดที่ได้รับการดูแลซึ่ง swagger-cli เองก็ชี้ไป มันครอบคลุมการตรวจสอบความถูกต้องและการรวมไฟล์แบบเดียวกัน จากนั้นเพิ่มกลไก linting ที่แท้จริงเข้าไป

การย้ายไปใช้ Redocly CLI

การย้ายข้อมูลมีขนาดเล็กเพราะชื่อคำสั่งใกล้เคียงกัน ติดตั้งตัวสืบทอด:

npm install -g @redocly/cli

คำสั่งที่เทียบเท่ากับ validate คือ lint หากต้องการให้ใกล้เคียงกับพฤติกรรมเดิม ให้ขยาย ruleset ขั้นต่ำ:

redocly lint --extends=minimal openapi.yaml

รันด้วย ruleset เริ่มต้นแทน แล้วมันจะบังคับใช้ชุดกฎที่แนะนำที่เข้มงวดขึ้น ซึ่งเป็นจุดที่ค่าของการ linting ปรากฏขึ้น คุณสามารถกำหนดค่ากฎในไฟล์ redocly.yaml ตั้งค่าแต่ละข้อเป็น error หรือ warn และยังสามารถเขียนปลั๊กอินที่กำหนดเองสำหรับการตรวจสอบเฉพาะองค์กรได้

การรวมไฟล์ (Bundling) ก็เทียบเท่ากันเกือบทุกประการ:

redocly bundle openapi.yaml -o dist/openapi.yaml

ชื่อแฟล็กเปลี่ยนไปเล็กน้อย -o/--outfile ของ swagger-cli กลายเป็น --output, -t/--type กลายเป็น --ext, และ -r/--dereference กลายเป็น -d/--dereferenced หากสคริปต์เก่าของคุณใช้แฟล็กแบบสั้น การค้นหาและแทนที่อย่างรวดเร็วก็จะช่วยให้คุณใช้งานได้ สำหรับการเปรียบเทียบเครื่องมือตรวจสอบสเปกที่กว้างขึ้น การวิเคราะห์เครื่องมือตรวจสอบ OpenAPI ที่ดีที่สุด จะนำ Redocly มาเปรียบเทียบกับทางเลือกอื่น

สรุปสั้นๆ: หากคุณกำลังเริ่มต้นใหม่ ให้เลือกใช้ Redocly CLI หากคุณมีขั้นตอน swagger-cli ที่มีอยู่ซึ่งใช้งานได้ดี ก็ไม่ต้องรีบร้อน แต่เส้นทางข้างหน้าชัดเจนและการเปลี่ยนชื่อก็เป็นเรื่องทางเทคนิค

ครึ่งหนึ่งที่เครื่องมือสเปกไม่สามารถครอบคลุมได้

นี่คือข้อจำกัดของเครื่องมือทุกอย่างที่เราได้กล่าวมาแล้ว swagger-cli validate ยืนยันว่าสเปกของคุณมีรูปแบบที่ถูกต้อง redocly lint ยืนยันว่ามันเป็นไปตามสไตล์ของคุณ ไม่มีเครื่องมือใดส่งคำขอเดียวไปยัง API ที่กำลังทำงานอยู่ของคุณเลย สเปกอาจสมบูรณ์แบบบนกระดาษในขณะที่การใช้งานจริงส่งคืนค่า 500, ขาดฟิลด์ที่สัญญาไว้ หรือละเลยพารามิเตอร์ของคิวรีทั้งหมด

การปิดช่องว่างนั้นหมายถึงการทดสอบการทำงาน (functional testing): ส่งคำขอจริงไปยัง endpoint จริง จากนั้นยืนยันรหัสสถานะ, เนื้อหาการตอบกลับ และค่าที่อยู่ภายใน นั่นคือหมวดหมู่เครื่องมือที่แตกต่างกัน และเป็นที่ที่ Apidog เข้ามามีบทบาทในเวิร์กโฟลว์

Apidog เป็นแพลตฟอร์ม API แบบ all-in-one คุณนำเข้าสเปก OpenAPI ของคุณ และจากคำจำกัดความเดียว คุณจะได้รับเอกสารเชิงโต้ตอบ, เซิร์ฟเวอร์ mock และสถานการณ์ทดสอบที่คุณสามารถเชื่อมโยงเข้าด้วยกันพร้อมกับการยืนยัน ทั้งหมดนี้โดยไม่ต้องออกจากพื้นที่ทำงาน การนำเข้าทำได้โดยตรง; คู่มือเกี่ยวกับ การนำเข้า Swagger หรือ OpenAPI และการสร้างคำขอที่รันได้ จะแนะนำขั้นตอน และคุณสามารถ สร้างชุดการทดสอบเต็มรูปแบบโดยตรงจากสเปก แทนที่จะสร้างด้วยมือ

ส่วนที่สำคัญสำหรับเทอร์มินัลคือตัวรัน command-line ซึ่งเผยแพร่เป็นแพ็คเกจ npm ชื่อ apidog-cli คุณติดตั้งและรันสถานการณ์ที่บันทึกไว้โดยไม่มีส่วนแสดงผล (headless):

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

แฟล็ก -t คือ ID สถานการณ์ทดสอบ, -e คือ ID สภาพแวดล้อม และ -r เลือกรูปแบบรายงานเช่น cli, html, json หรือ junit เช่นเดียวกับ swagger-cli มันจะออกด้วยรหัสสถานะที่ชัดเจน ดังนั้นการยืนยันที่ล้มเหลวจะทำให้ pipeline เป็นสีแดง แตกต่างจาก swagger-cli ตรงที่สิ่งที่มันตรวจสอบคือพฤติกรรมจริงของ API ของคุณ ไม่ใช่แค่รูปร่างของไฟล์ที่อธิบายมัน สำหรับข้อมูลอ้างอิงแฟล็กทั้งหมดและตัวอย่าง CI โปรดดู คู่มือฉบับสมบูรณ์ของ Apidog CLI หรือรัน apidog run --help เพื่อดูตัวเลือกปัจจุบัน หากคุณต้องการตั้งค่าสถานการณ์แรก ดาวน์โหลด Apidog นำเข้าสเปกของคุณ แล้วคำสั่งรันจะคัดลอกได้จากแท็บ CI/CD ของสถานการณ์นั้น

เวิร์กโฟลว์เทอร์มินัลที่สมบูรณ์

นำสองส่วนมารวมกัน คุณก็จะได้ pipeline ที่ตรวจสอบทั้งสัญญา (contract) และการใช้งานจริงตามลำดับ:

# 1. สเปกมีรูปแบบถูกต้องและเป็นไปตามสไตล์หรือไม่?
redocly lint --extends=minimal openapi.yaml

# 2. สร้างเอกสารเดียวที่สามารถเผยแพร่ได้
redocly bundle openapi.yaml -o dist/openapi.yaml

# 3. API ที่กำลังทำงานอยู่ตรงกับสัญญาจริงหรือไม่?
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit

ขั้นตอนแรกจะล้มเหลวอย่างรวดเร็วหากสเปกมีรูปแบบผิดพลาดหรือไม่เป็นไปตามสไตล์ ขั้นตอนที่สองจะสร้าง artifact ที่เอกสารและตัวสร้าง SDK ของคุณใช้ ขั้นตอนที่สามจะส่งทราฟฟิกจริงและยืนยันการตอบกลับ ดังนั้น build ที่เป็นสีเขียวหมายความว่าทั้งสัญญาและโค้ดเบื้องหลังนั้นสมบูรณ์ แต่ละขั้นตอนจะออกด้วย exit code ที่ไม่ใช่ศูนย์เมื่อล้มเหลว ดังนั้นทั้งสายโซ่นี้จึงเป็นด่านเดียวที่คุณสามารถใส่ลงใน CI runner ใดๆ ที่มี Node

หากการทดสอบของคุณในปัจจุบันอาศัยเครื่องมือที่สอดคล้องกับสเปกที่เงียบไปแล้ว บทความเกี่ยวกับ การตรวจสอบความถูกต้องของ API กับสเปกโดยไม่มี Dredd ครอบคลุมแนวคิดเดียวกันของสัญญาเทียบกับการใช้งานจริงจากมุมที่แตกต่างกัน

ข้อสังเกตเกี่ยวกับ swagger-codegen

ผู้ที่ค้นหา “swagger cli” บางครั้งอาจหมายถึง swagger-codegen ซึ่งเป็นเครื่องมือที่แตกต่างกันและมีหน้าที่ต่างกัน มันอ่านสเปก OpenAPI และสร้าง client SDKs, server stubs และเอกสารในภาษาต่างๆ มากมาย มันมีประโยชน์อย่างแท้จริงสำหรับการเริ่มต้นใช้งาน client แบบมีประเภทข้อมูล (typed client) จากสเปกที่เผยแพร่ และเป็นธรรมที่จะเรียกมันว่าเป็นตัวเลือกการสร้างโค้ดที่มีความสามารถมากที่สุดในตระกูล Swagger

มันไม่ทำการตรวจสอบความถูกต้อง, lint, หรือทดสอบในความหมายที่บทความนี้ครอบคลุม การสร้างโค้ดสมมติว่าคุณมีสเปกที่สมบูรณ์อยู่แล้ว; หากอินพุตเสีย ผลลัพธ์ก็จะเสียตามไปด้วย ดังนั้นแม้ในเวิร์กโฟลว์การสร้างโค้ด คุณยังคงต้องการขั้นตอนการตรวจสอบความถูกต้องหรือ lint ก่อนหน้านั้น เครื่องมือเหล่านี้ส่งเสริมซึ่งกันและกันมากกว่าที่จะมาแทนที่กัน

button

ฝึกการออกแบบ API แบบ Design-first ใน Apidog

ค้นพบวิธีที่ง่ายขึ้นในการสร้างและใช้ API