Redocly CLI เป็นเครื่องมือที่ดี หากคุณเคยใช้มันเพื่อตรวจสอบ (lint) ไฟล์ OpenAPI, รวมสเปกหลายไฟล์ให้เป็นไฟล์เดียว, หรือสร้างเอกสาร Redoc จากเทอร์มินัล คุณก็คงรู้ดีอยู่แล้ว แล้วทำไมถึงยังต้องมองหาทางเลือกอื่นแทน Redocly CLI ด้วย?
โดยปกติแล้วมันขึ้นอยู่กับ "รูปแบบ" Redocly CLI เป็นผู้เชี่ยวชาญที่เน้นการทำงานกับโค้ดเป็นหลัก: ตรวจสอบ (lint), รวม (bundle), แยก (split), เชื่อม (join), สร้างเอกสาร นั่นคือสิ่งที่เหมาะสมอย่างยิ่งสำหรับบางทีม และไม่เพียงพอสำหรับทีมอื่น ๆ หากคุณต้องการเครื่องมือเดียวที่ยังสามารถออกแบบ, สร้าง Mock และทดสอบ API ได้ด้วย CLI ไม่ได้พยายามเป็นเครื่องมือแบบนั้น และก็ไม่ควรเป็น
บทความนี้เกี่ยวกับ Redocly CLI (แพ็คเกจโอเพนซอร์ส @redocly/cli) ไม่ใช่ผลิตภัณฑ์ Redocly docs แบบโฮสต์ หากคุณกำลังเปรียบเทียบแพลตฟอร์มเอกสารแบบโฮสต์หรือ Redoc เอง ให้อ่าน บทสรุปทางเลือกของ Redocly สำหรับเอกสาร API แทน โพสต์นี้สำหรับผู้ที่พิมพ์ redocly lint และ redocly bundle และต้องการทราบว่ามีอะไรอีกบ้างที่เหมาะกับขั้นตอนการทำงานของพวกเขา
Redocly CLI ทำอะไรได้ดีจริง ๆ
Redocly CLI เป็นโอเพนซอร์สและทำงานบนเทอร์มินัล คุณติดตั้งเพียงครั้งเดียวและจะได้ชุดคำสั่งที่กระชับซึ่งทำงานได้อย่างสะอาดหมดจด เอกสาร Redocly CLI ครอบคลุมทั้งหมด แต่สรุปสั้นๆ ได้ดังนี้
การตรวจสอบ (Linting) เป็นจุดแข็งที่เป็นเอกลักษณ์ redocly lint ตรวจสอบความถูกต้องของคำอธิบาย OpenAPI, AsyncAPI, Arazzo หรือ Open-RPC ของคุณ จากนั้นจะเรียกใช้กฎตามสไตล์ไกด์ คุณกำหนดค่าทุกอย่างผ่านไฟล์ redocly.yaml: เลือกชุดกฎในตัว (minimal, recommended, recommended-strict, หรือ spec) หรือสร้างกฎของคุณเอง การกำกับดูแลที่ขับเคลื่อนด้วยการกำหนดค่านี้ยากที่จะเอาชนะได้ หากคุณต้องการบังคับใช้การออกแบบ API ที่สอดคล้องกันใน CI ทั่วทั้งหลายทีม
npm install -g @redocly/cli@latest
redocly lint openapi.yaml
Bundle, split และ join จัดการการเชื่อมต่อสเปก redocly bundle ตามตัวชี้ $ref และสร้างไฟล์รวมฉบับเดียว redocly split ทำตรงกันข้าม โดยแยกคำอธิบายเดียวออกเป็นโครงสร้างไฟล์หลายไฟล์ redocly join (ทดลอง) รวมไฟล์ OpenAPI หลายไฟล์เข้าด้วยกันเป็นไฟล์เดียว
redocly bundle openapi.yaml --output dist/openapi.json
เอกสารมาจาก build-docs มันสร้างหน้า HTML Redoc แบบสแตนด์อโลน และ preview-docs ให้คุณดูตัวอย่างแบบสดในเครื่องได้
redocly build-docs openapi.yaml -o docs.html
ดังนั้น หากความต้องการของคุณคือ "ตรวจสอบตามสไตล์ไกด์, รวมสเปก, และเผยแพร่เอกสาร Redoc ทั้งหมดนี้จากเทอร์มินัล" Redocly CLI คือตัวเลือกเริ่มต้นที่แข็งแกร่ง หลายทีมควรใช้มันต่อไป เหตุผลที่มองหาทางเลือกอื่นนั้นเกี่ยวกับขอบเขต ไม่ใช่คุณภาพ
ทำไมผู้คนถึงมองหาทางเลือกอื่น
มีรูปแบบบางอย่างที่ปรากฏขึ้นซ้ำแล้วซ้ำอีก:
- คุณต้องการแพลตฟอร์มแบบครบวงจร ไม่ใช่แค่การตรวจสอบ (lint) และเอกสาร (docs) เท่านั้น Redocly CLI ไม่ได้รันการทดสอบ API และไม่ได้โฮสต์เซิร์ฟเวอร์ Mock หากคุณต้องการออกแบบ, Mock และมีตัวรันการทดสอบด้วย คุณจะต้องประกอบชุดเครื่องมือเข้าด้วยกัน
- คุณต้องการ GUI ควบคู่ไปกับ CLI Redocly ถูกออกแบบมาโดยเน้นการทำงานกับโค้ดเป็นหลัก หากทีมของคุณมีคนที่ต้องการทำงานด้วยภาพมากกว่า การกำกับดูแลที่ใช้เทอร์มินัลเท่านั้นอาจขายยาก
- คุณต้องการตัวรันการทดสอบในตัวสำหรับ CI การตรวจสอบ (Linting) จะจับปัญหาของสเปกได้ มันไม่ได้บอกว่า API ที่ทำงานอยู่นั้นทำงานได้ดีหรือไม่ นั่นเป็นเครื่องมือแยกต่างหาก
- คุณไม่ต้องการเชื่อมโยงเครื่องมือห้าอย่างเข้าด้วยกัน Spectral สำหรับการตรวจสอบ (lint), Redocly สำหรับการรวม (bundle) และเอกสาร (docs), Postman หรือ Newman สำหรับการทดสอบ, และอย่างอื่นสำหรับ Mocking สิ่งนั้นใช้ได้ผล แต่มีส่วนประกอบที่เคลื่อนไหวได้มากเกินไปที่จะต้องดูแลรักษา
แต่ละจุดชี้ไปที่ทางเลือกที่แตกต่างกัน มาจับคู่กัน
รายการตัวเลือกสั้นๆ ตามสิ่งที่คุณต้องการจริงๆ
Apidog ถ้าคุณต้องการแพลตฟอร์มเดียวสำหรับวงจรชีวิต API ทั้งหมด
Apidog เป็นแพลตฟอร์ม API แบบครบวงจร: การออกแบบ, Mocking, การทดสอบ และเอกสารประกอบในที่เดียว พร้อม CLI สำหรับการนำเข้า, ส่งออก และการรันการทดสอบ CI เป็นตัวเลือกที่เหมาะสมเมื่อคุณต้องการเครื่องมือเดียวสำหรับวงจรชีวิตทั้งหมด แทนที่จะต้องเชื่อมต่อ Linter, Bundler, Test Runner และ Mock Server เข้าด้วยกัน
นี่คือส่วนที่จริงใจ Apidog ไม่มี linter สไตล์ไกด์ที่กำหนดค่าได้และเน้นโค้ดเป็นหลัก พร้อมชุดกฎที่กำหนดเองได้เหมือน lint ของ Redocly ไม่มีคำสั่ง apidog lint และไม่มีวิธีสร้างกฎที่กำหนดเองในสไตล์ Spectral หรือ Redocly ผ่าน CLI Apidog ตรวจสอบโครงสร้างเมื่อคุณนำเข้าสเปก แต่หากการกำกับดูแลการออกแบบที่เข้มงวดและปรับแต่งได้เป็นสิ่งเดียวที่คุณให้ความสำคัญ Apidog จะไม่สามารถแทนที่ redocly lint ได้ด้วยตัวมันเอง ใช้คู่กับ Spectral สำหรับงานนั้น เราจะกลับมาพูดถึงเรื่องนี้อีกครั้ง
สิ่งที่ Apidog ให้คุณได้ซึ่ง Redocly CLI ไม่มี: โปรแกรมออกแบบภาพ, เซิร์ฟเวอร์ Mock ในตัว, โปรแกรมสร้างการทดสอบภาพ, และตัวรันการทดสอบ CI CLI จัดการส่วนที่อยู่ในเทอร์มินัล
# ติดตั้งและยืนยันตัวตน (โทเค็นจากแอป: อวตาร > ตั้งค่าบัญชี > โทเค็นการเข้าถึง API)
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
# นำเข้าสเปกเข้าสู่โปรเจกต์ (ตรวจสอบความถูกต้อง + แก้ไข $refs หลายไฟล์)
apidog import --project 123456 --format openapi --file ./openapi.json
# ส่งออกไฟล์รวมฉบับเดียว และเลือกเวอร์ชัน OpenAPI ของคุณ
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# รันสถานการณ์การทดสอบใน CI ด้วยรูปแบบรายงานหลายรูปแบบ
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
apidog import ทำหน้าที่ตรวจสอบเมื่อนำเข้า และ apidog export ทำหน้าที่รวมเมื่อส่งออก (มันส่งออกไฟล์เดียวและสามารถอัปเกรดเวอร์ชัน OAS ได้) รายการคำสั่งทั้งหมดอยู่ใน เอกสาร Apidog CLI และ คู่มือ Apidog CLI ฉบับสมบูรณ์ ของเราจะอธิบายทุกแฟล็ก เหมาะที่สุดสำหรับ: ทีมที่ต้องการการออกแบบ, Mock, ทดสอบ และเอกสารประกอบในแพลตฟอร์มเดียว
Spectral ถ้าสิ่งที่คุณต้องการจาก Redocly มีแค่ Linter
หากสิ่งเดียวที่คุณใช้คือ redocly lint คุณไม่จำเป็นต้องเปลี่ยนแพลตฟอร์ม Spectral จาก Stoplight คือ Linter แบบโอเพนซอร์สที่ใช้กฎ ซึ่งทับซ้อนกับการตรวจสอบของ Redocly โดยตรงที่สุด คุณเขียนกฎใน YAML, รันกฎเหล่านั้นกับเอกสาร OpenAPI หรือ AsyncAPI ใดๆ ก็ได้ และเชื่อมต่อเข้ากับ CI
Spectral และ Redocly’s linter เป็นญาติสนิทกัน ทั้งคู่ขับเคลื่อนด้วยการกำหนดค่า ทั้งคู่มาพร้อมชุดกฎ และทั้งคู่ให้คุณสร้างกฎที่กำหนดเองได้ การเลือกระหว่างสองสิ่งนี้มักจะขึ้นอยู่กับความเหมาะสมของระบบนิเวศและรูปแบบชุดกฎที่ทีมของคุณรู้จักอยู่แล้ว การเจาะลึกเกี่ยวกับการตรวจสอบ OpenAPI ของ Spectral ของเราครอบคลุมการสร้างกฎ และ คู่มือการตรวจสอบ API ที่ครอบคลุมกว่าจะเปรียบเทียบภาพรวมของการตรวจสอบหากคุณต้องการข้อมูลทั้งหมด เหมาะที่สุดสำหรับ: ทีมที่มีความต้องการที่แท้จริงคือการตรวจสอบสเปกที่บริสุทธิ์และปรับแต่งได้
Scalar หรือ Bump.sh ถ้าคุณส่วนใหญ่ต้องการเอกสาร
หากส่วนของ Redocly CLI ที่คุณสนใจคือ build-docs ทางเลือกอื่นคือเครื่องมือสร้างเอกสาร ไม่ใช่แพลตฟอร์ม Scalar และ Bump.sh ทั้งคู่แปลงคำอธิบาย OpenAPI เป็นเอกสารอ้างอิงที่โฮสต์และสามารถเรียกดูได้ โดยแต่ละตัวมีรูปลักษณ์และชุดคุณสมบัติเป็นของตัวเอง พวกเขาเน้นประสบการณ์การสร้างเอกสารมากกว่าการตรวจสอบ (linting) หรือการทดสอบ เหมาะที่สุดสำหรับ: ทีมที่มีเป้าหมายหลักคือเอกสารอ้างอิง API ที่ดูดีและดูแลรักษาง่าย
swagger-cli ซึ่งไม่ใช่ตัวเลือกอีกต่อไปแล้ว
คุณจะยังคงเห็น swagger-cli ถูกกล่าวถึงในคู่มือเก่า ๆ ดังนั้นจึงควรอธิบายให้ชัดเจนว่า: swagger-cli เลิกใช้งานแล้ว คลัง GitHub ของ swagger-cli ระบุว่าไม่มีการบำรุงรักษาอีกต่อไป และแนะนำให้ผู้ใช้ไปที่ Redocly CLI เป็นตัวตายตัวแทน
มันเคยมีแค่สองคำสั่งคือ swagger-cli validate และ swagger-cli bundle มันไม่เคยตรวจสอบด้วยกฎสไตล์, ไม่เคยสร้างเอกสาร, ไม่เคยรันการทดสอบ, และไม่เคย Mock อะไรเลย หากคุณยังใช้อยู่ในวันนี้ การย้ายคือการเลิกใช้ ไม่ใช่การเปลี่ยนไปใช้ คู่มือของเราเกี่ยวกับ วิธีการใช้ swagger-cli ครอบคลุมสิ่งที่มันทำ และ Redocly ยังเผยแพร่ คู่มือการย้ายจาก swagger-cli พร้อมการแมปแฟล็กที่แน่นอน เราจะรวมการแมปนั้นไว้ด้านล่างเพื่อความสมบูรณ์
ตารางเปรียบเทียบ
นี่คือวิธีการจัดเรียงตัวเลือกเทียบกับงานที่ Redocly CLI จัดการ "Lint custom rules" หมายถึง linter สไตล์ไกด์ที่กำหนดค่าได้และเน้นโค้ดเป็นหลัก พร้อมชุดกฎที่กำหนดเองได้
| เครื่องมือ | Lint กฎที่กำหนดเอง | Bundle | Docs | Mock | Test | GUI | โอเพนซอร์ส | เหมาะที่สุดสำหรับ |
|---|---|---|---|---|---|---|---|---|
| Redocly CLI | ใช่ | ใช่ | ใช่ (Redoc) | ไม่ | ไม่ | ไม่ | ใช่ | การกำกับดูแลการตรวจสอบ, การรวม, และการสร้างเอกสารด้วยโค้ดเป็นหลักจากเทอร์มินัล |
| Apidog | ไม่ | ผ่านการส่งออก | ใช่ | ใช่ | ใช่ (CI runner) | ใช่ | ไม่ (ฟรีเมียม) | แพลตฟอร์มเดียวสำหรับการออกแบบ, Mock, ทดสอบ และเอกสารประกอบ |
| Spectral | ใช่ | ไม่ | ไม่ | ไม่ | ไม่ | ไม่ | ใช่ | การตรวจสอบ OpenAPI/AsyncAPI ที่บริสุทธิ์และปรับแต่งได้ |
| Scalar / Bump.sh | ไม่ | ไม่ | ใช่ | ไม่ | ไม่ | ใช่ | หลากหลาย | เอกสารอ้างอิง API ที่โฮสต์ |
| swagger-cli | ไม่ | ใช่ | ไม่ | ไม่ | ไม่ | ไม่ | ใช่ (เลิกใช้แล้ว) | ไม่มีอะไรใหม่, ไม่มีการบำรุงรักษา |
ข้อสังเกตเกี่ยวกับตาราง: "ผ่านการส่งออก" ของ Apidog หมายถึง apidog export จะสร้างไฟล์รวมฉบับเดียว ซึ่งครอบคลุมเหตุผลในทางปฏิบัติที่คุณจะรัน redocly bundle แต่ไม่ใช่คำสั่ง bundle ที่เหมือนกันทุกประการ และ Apidog เป็นฟรีเมียม ไม่ใช่โอเพนซอร์ส ในขณะที่ Redocly CLI และ Spectral เป็นโอเพนซอร์สทั้งคู่ เรียกสิ่งเหล่านี้ว่าข้อแลกเปลี่ยน
การแมปแฟล็ก bundle ของ swagger-cli ไปยัง Redocly CLI
หากคุณกำลังใช้ swagger-cli ที่เลิกใช้งานแล้ว และ Redocly เป็นปลายทางสำหรับการรวม (bundling) แฟล็กต่างๆ จะถูกแมปอย่างชัดเจน:
| swagger-cli | Redocly CLI | ความหมาย |
|---|---|---|
-o, --outfile <file> |
--output (หรือ -o) |
เขียนลงในไฟล์แทนที่จะเป็น stdout |
-t, --type <json|yaml> |
--ext <json|yaml|yml> |
ประเภทไฟล์เอาต์พุต |
-r, --dereference |
-d, --dereferenced |
รวม $refs ทั้งหมดเข้าเป็นอินไลน์เต็มรูปแบบ |
ดังนั้น swagger-cli bundle -o output.json จะกลายเป็น redocly bundle --output output.json
คำแนะนำที่ชัดเจน
ไม่มีผู้ชนะเพียงคนเดียว เพราะคำตอบที่ถูกต้องขึ้นอยู่กับว่าคุณกำลังพยายามแทนที่งานใดของ Redocly CLI
ใช้ Redocly CLI ต่อไป หากการกำกับดูแลของมันเป็นสิ่งที่คุณต้องการอย่างแท้จริง Linter, Bundler และตัวสร้างเอกสาร Redoc ที่ขับเคลื่อนด้วยการกำหนดค่าแบบโอเพนซอร์สที่ทำงานได้อย่างเบาและรวดเร็วซึ่งคุณรันจากเทอร์มินัลเท่านั้น ถือเป็นการตั้งค่าที่ดีอย่างแท้จริง ไม่มีสิ่งใดในที่นี้เป็นเหตุผลที่จะทิ้งเครื่องมือที่เหมาะสม
เลือก Apidog หากคุณเบื่อกับการประกอบชุดเครื่องมือและต้องการการออกแบบ, Mocking, การทดสอบ และเอกสารประกอบในแพลตฟอร์มเดียวพร้อม CLI สำหรับส่วนที่เกี่ยวกับเทอร์มินัล คุณจะเลิกดูแลรักษาเครื่องมือแยกต่างหากสำหรับแต่ละขั้นตอน และได้ GUI สำหรับคนในทีมของคุณที่ต้องการมัน แค่ต้องชัดเจนว่าคุณจะใช้คู่กับ Spectral หากคุณต้องการการตรวจสอบกฎที่กำหนดเอง คู่มือ Apidog CLI ใน CI/CD แสดงให้เห็นว่าตัวรันการทดสอบทำงานอย่างไรในไปป์ไลน์ และ การเปรียบเทียบ Apidog CLI กับ Newman จะเปรียบเทียบกับตัวรันที่หลายทีมใช้อยู่แล้ว คุณสามารถ ดาวน์โหลด Apidog และทดลองใช้ฟรีโดยไม่ต้องใช้บัตรเครดิต
เลือก Spectral หากการตรวจสอบ (linting) เป็นจุดประสงค์หลัก อย่าเปลี่ยนแพลตฟอร์มเพื่อแทนที่คำสั่งเดียว
การอธิบายอย่างตรงไปตรงมา: Redocly เป็นผู้เชี่ยวชาญ CLI ที่เน้นโค้ดเป็นหลัก และ Apidog เป็นแพลตฟอร์มภาพแบบครบวงจร ทั้งสองเป็นกระบวนทัศน์ที่แตกต่างกัน ไม่ใช่การสับเปลี่ยนแบบแทนที่ได้ทันที เลือกตามความเหมาะสม
คำถามที่พบบ่อย
Apidog เป็นตัวแทนโดยตรงสำหรับ Redocly CLI ใช่หรือไม่? ไม่ใช่ และควรพูดตรงไปตรงมาเรื่องนี้ Apidog ครอบคลุมวงจรชีวิตได้มากขึ้น (ออกแบบ, Mock, ทดสอบ, เอกสาร) แต่ไม่มี linter ที่มีชุดกฎที่กำหนดเองเหมือน redocly lint หากการกำกับดูแลสเปกที่เข้มงวดและปรับแต่งได้คือภารกิจหลักของคุณ ให้ใช้ linter ของ Redocly ต่อไป หรือใช้ Spectral Apidog ชนะเมื่อคุณต้องการเครื่องมือเดียวสำหรับวงจรชีวิต API ทั้งหมดแทนที่จะใช้หลายเครื่องมือ
Apidog CLI มีคำสั่ง lint หรือไม่? ไม่มี Apidog ตรวจสอบโครงสร้างเมื่อคุณนำเข้าสเปกด้วย apidog import แต่ไม่มี apidog lint และไม่มีวิธีสร้างกฎที่กำหนดเองในสไตล์ Spectral หรือ Redocly ผ่าน CLI สำหรับเรื่องนั้น ให้ใช้ Apidog คู่กับ Spectral
ฉันสามารถรวมไฟล์ OpenAPI โดยไม่ใช้ Redocly CLI ได้หรือไม่? ได้ apidog export --project <id> --format openapi --output ./openapi.json จะส่งออกไฟล์รวมฉบับเดียว และสามารถกำหนดเป้าหมายเวอร์ชัน OpenAPI ที่เฉพาะเจาะจงด้วย --oas-version มันไม่ใช่คำสั่ง bundle โดยตรง แต่ครอบคลุมความต้องการในทางปฏิบัติแบบเดียวกัน หากคุณต้องการแค่การรวมเท่านั้น redocly bundle ก็ยังคงเป็นตัวเลือกที่ดีและเน้นการทำงาน
ฉันควรใช้ swagger-cli ในปี 2026 หรือไม่? ไม่ควร swagger-cli เลิกใช้งานแล้วและไม่มีการบำรุงรักษา คลังของมันเองก็ชี้ไปที่ Redocly CLI เป็นตัวตายตัวแทน มันเคยเพียงแค่ตรวจสอบและรวมไฟล์เท่านั้น ใช้ Redocly CLI สำหรับงานนั้น หรือย้ายไปใช้แพลตฟอร์มอย่าง Apidog หากคุณต้องการส่วนที่เหลือของวงจรชีวิตด้วย
ความแตกต่างระหว่างสิ่งนี้กับการเปรียบเทียบแพลตฟอร์ม Redocly docs คืออะไร? โพสต์นี้เกี่ยวกับเครื่องมือโอเพนซอร์ส @redocly/cli: ตรวจสอบ (lint), รวม (bundle), แยก (split), เชื่อม (join) และสร้างเอกสาร (build-docs) หากคุณกำลังเปรียบเทียบผลิตภัณฑ์ Redocly docs แบบโฮสต์หรือ Redoc ในฐานะตัวแสดงผลเอกสาร ให้อ่าน ทางเลือกของ Redocly สำหรับเอกสาร API แทน ทั้งสองครอบคลุมผลิตภัณฑ์ที่แตกต่างกันซึ่งบังเอิญมีชื่อเหมือนกัน สำหรับสเปกเอง OpenAPI Specification คือแหล่งข้อมูลที่ถูกต้องที่สุด และ Redocly CLI บน npm คือที่ที่คุณจะพบรายละเอียดการติดตั้งปัจจุบัน