Apidog CLI เทียบกับ Redocly CLI: API CLI ตัวไหนที่คุณควรเลือกใช้

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

นี่คือการเปรียบเทียบระดับคำสั่งโดยตรงระหว่าง Apidog CLI และ Redocly CLI ไม่มีข้อโต้แย้ง Redocly CLI เป็นซอฟต์ต์แวร์โอเพนซอร์สที่ดีอย่างแท้จริง และคุณจะได้เห็นว่ามันโดดเด่นตรงไหนก่อนที่จะมีการตัดสินใจใดๆ

สรุปโดยย่อ (TL;DR)

พวกมันแก้ปัญหาที่ทับซ้อนกันแต่แตกต่างกัน

Redocly CLI (@redocly/cli, ไบนารี redocly) เป็นผู้เชี่ยวชาญด้าน OpenAPI แบบเน้นโค้ดเป็นหลัก: lint ด้วยชุดกฎที่กำหนดเอง, รวมสเปคหลายไฟล์, แยกและรวมเข้าด้วยกัน, และสร้างเอกสาร HTML แบบสแตนด์อโลน เป็นโอเพนซอร์ส, ขับเคลื่อนด้วยการกำหนดค่า, และทำงานได้ดีในเทอร์มินัล หากสเปคของคุณคือแหล่งความจริงและอยู่ใน Git นี่คือการกำกับดูแลที่คุณสั่งงานจากบรรทัดคำสั่ง

Apidog CLI (apidog-cli, ไบนารี apidog) คือส่วนหน้าของแพลตฟอร์ม API แบบครบวงจรที่ทำงานบนบรรทัดคำสั่ง มันนำเข้าและส่งออกคำจำกัดความไปยังโปรเจกต์ และรันสถานการณ์ทดสอบ API ใน CI ด้วยรายงาน JUnit และ HTML มันมีคุณค่าเมื่อสเปคเดียวกันนั้นจำเป็นต้องถูกจำลอง, ทดสอบ, และจัดทำเอกสารในพื้นที่ทำงานเดียว แทนที่จะต้องประกอบจากเครื่องมือที่แยกต่างหาก

เลือก Redocly CLI เมื่อคุณต้องการ Linter, Bundler, และ Doc-builder แบบโอเพนซอร์สที่มีน้ำหนักเบาและทำงานจากเทอร์มินัลเท่านั้น เลือก Apidog เมื่อคุณต้องการเครื่องมือเดียวสำหรับวงจรชีวิต API ทั้งหมด พวกมันยังสามารถทำงานร่วมกันได้ และส่วนสุดท้ายจะอธิบายวิธีการ

ปรัชญาที่แตกต่างกันสองแบบ

Redocly CLI เน้นไฟล์เป็นศูนย์กลางและโค้ดเป็นหลัก เอกสาร OpenAPI บนดิสก์คือสิ่งที่คุณดำเนินการ ทุกคำสั่ง เช่น redocly lint, redocly bundle, redocly build-docs จะรับพาธไปยังไฟล์และทำงานในเครื่อง โดยไม่มีบัญชีและไม่มีเซิร์ฟเวอร์เข้ามาเกี่ยวข้อง พฤติกรรมถูกกำหนดโดยการกำหนดค่า redocly.yaml ที่คุณตรวจสอบเข้าไปในรีโพถัดจากสเปค โมเดลนี้เหมาะสำหรับทีมที่ถือว่าคำอธิบาย API ของพวกเขาเป็นซอร์สโค้ด: ตรวจสอบในการดึงคำขอ, ป้องกันใน CI, และจัดเวอร์ชันเหมือนสิ่งอื่นๆ OpenAPI Specification คือสัญญา และ Redocly CLI คือชุดเครื่องมือที่คอยกำกับดูแล

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

ปรัชญาทั้งสองแบบไม่มีผิด พวกมันเหมาะกับทีมที่แตกต่างกัน ความแตกต่างที่แท้จริงคือ: Redocly มอบ CLI แบบโอเพนซอร์สที่เน้นเฉพาะสำหรับการกำกับดูแลสเปค และ Apidog มอบ CLI สู่แพลตฟอร์มที่กว้างขวางกว่า

คำสั่งต่อคำสั่ง

นี่คือส่วนสำคัญที่ถูกจับคู่ตามงาน คำสั่งทุกคำสั่งด้านล่างเป็นของจริง ไม่มีสิ่งใดถูกสร้างขึ้น

บางแถวเหล่านี้สมควรได้รับหมายเหตุที่ชัดเจน เพราะความแตกต่างนั้นเป็นของจริงและบทความนี้จะไม่ซื่อสัตย์หากไม่มีการกล่าวถึง

Linting เป็นพื้นที่ของ Redocly ไม่ใช่ของ Apidog Redocly CLI lint OpenAPI, AsyncAPI, Arazzo และ Open-RPC กับชุดกฎที่กำหนดค่าได้ และคุณสามารถเขียนกฎของคุณเองได้ Apidog ตรวจสอบความถูกต้องของโครงสร้างคำจำกัดความเมื่อคุณนำเข้า แต่ไม่มี apidog lint ไม่มี config แบบ redocly.yaml และไม่มีวิธีเขียนกฎสไตล์ไกด์ที่กำหนดเองผ่าน CLI หากเป้าหมายของคุณคือสไตล์ไกด์ที่เน้นโค้ดเป็นหลักซึ่งบังคับใช้ในเทอร์มินัล Redocly คือเครื่องมือ Apidog ไม่ได้แข่งขันในจุดนี้ และการกล่าวเป็นอย่างอื่นก็จะเป็นการผิด

Split และ Join เป็นของ Redocly redocly split แยกคำอธิบายเดียวออกเป็นโครงสร้างหลายไฟล์ และ redocly join (ทดลอง) รวมหลายไฟล์เข้าเป็นไฟล์เดียว Apidog ไม่มีคำสั่งทั้งสอง การนำเข้าของมันจะแก้ไข $ref ของหลายไฟล์ให้เป็นทรัพยากรที่รวมเป็นหนึ่ง และการส่งออกของมันจะสร้างไฟล์รวมเดียว แต่ก็ไม่เหมือนกับยูทิลิตี้ split/join แบบสแตนด์อโลนที่คุณรันกับไฟล์ที่แยกต่างหาก

การรันการทดสอบและการจำลองเป็นของ Apidog Redocly CLI ไม่ทำการทดสอบ API และไม่ได้โฮสต์เซิร์ฟเวอร์จำลอง; นั่นอยู่นอกขอบเขตการออกแบบของมัน Apidog รันสถานการณ์การทดสอบแบบ headless ด้วย apidog run และสร้างรายงาน JUnit, HTML, JSON และ CLI สำหรับไปป์ไลน์ของคุณ และการจำลองเป็นคุณสมบัติหลักของแพลตฟอร์ม (สร้างในแอป ไม่ได้ขับเคลื่อนจาก CLI)

ทั้งคู่สร้างเอกสาร HTML จากเทอร์มินัล redocly build-docs สร้างไฟล์ Redoc HTML แบบสแตนด์อโลน apidog export --format html เขียนไฟล์เอกสาร HTML จากโปรเจกต์ของคุณ เครื่องมือต่างกัน ผลลัพธ์ในเทอร์มินัลเหมือนกัน

คำสั่ง Redocly CLI จริง

ติดตั้งแบบโกลบอล หรือข้ามการติดตั้งแล้วรันผ่าน npx:

npm install -g @redocly/cli@latest
# หรือ, ไม่ต้องติดตั้งแบบโกลบอล:
npx @redocly/cli@latest lint openapi.yaml

Lint สเปค เมื่อมี redocly.yaml อยู่ คำสั่งนี้จะใช้ชุดกฎที่คุณเลือก (minimal, recommended, recommended-strict, spec, หรือกฎที่กำหนดเอง):

redocly lint openapi.yaml

หากคุณต้องการเพียงการตรวจสอบโครงสร้างแบบธรรมดา ซึ่งเป็นแบบที่ swagger-cli ที่เลิกใช้ไปแล้วเคยทำ ให้กำหนดค่า redocly.yaml ด้วยกฎ spec เท่านั้น แล้วรัน redocly lint เหมือนเดิม Redocly เผยแพร่ คู่มือการย้ายจาก swagger-cli เนื่องจาก Redocly CLI เป็นผู้สืบทอดที่ระบุไว้ ที่เก็บ swagger-cli ตอนนี้มีประกาศการเลิกใช้งานด้วยเหตุผลเดียวกัน เครื่องมือเก่าเหล่านั้นเพียงแค่ตรวจสอบและรวม ไม่เคย lint ด้วยกฎสไตล์

รวมคำจำกัดความหลายไฟล์เข้าเป็นไฟล์เดียว โดยตามทุก $ref:

redocly bundle openapi.yaml --output bundled.json

หากคุณมาจาก swagger-cli แฟล็กต่างๆ จะถูกแมปอย่างชัดเจน: -o/--outfile กลายเป็น --output, -t/--type กลายเป็น --ext (json, yaml, หรือ yml), และ -r/--dereference กลายเป็น -d/--dereferenced.

สร้างเอกสาร HTML แบบสแตนด์อโลนด้วย Redoc:

redocly build-docs openapi.yaml -o docs.html

แยกคำอธิบายเดียวออกเป็นโครงสร้างหลายไฟล์ ซึ่งเป็นการกระทำที่ตรงกันข้ามกับการรวมเข้าด้วยกัน:

redocly split openapi.yaml --outDir ./split-spec

สำหรับการเปรียบเทียบ Redocly กับเครื่องมืออื่นๆ ในหมวดหมู่นี้อย่างละเอียด คู่มือการตั้งค่า OpenAPI linter ครอบคลุม Spectral, Redocly และ Vacuum เคียงข้างกัน และ การรวบรวมทางเลือก Redocly ครอบคลุมแพลตฟอร์มเอกสารโดยเฉพาะ

คำสั่ง Apidog CLI จริง

ติดตั้ง CLI และยืนยันตัวตนด้วยโทเค็นจากแอป (อวตาร, จากนั้น Account Settings, จากนั้น API Access Token):

npm install -g apidog-cli@latest
apidog login --with-token <TOKEN>

โทเค็นจะอยู่ใน ~/.apidog/config.toml อย่าพิมพ์หรือ commit มัน

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

apidog import --project 123456 --format openapi --file ./openapi.json

การนำเข้ายอมรับมากกว่า OpenAPI: Postman, HAR, Insomnia, JMeter, WSDL, YApi, RAP2, apiDoc, Hoppscotch, Markdown, JSON Schema และรูปแบบเฉพาะของ Apidog

ส่งออกไฟล์รวมเดียวที่ถูกรวมเข้าด้วยกัน โดยเลือกที่จะอัปเกรดเวอร์ชัน OpenAPI นี่คือการรวมไฟล์พร้อมกับการอัปเดตเวอร์ชันในขั้นตอนเดียว:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

ส่งออกเอกสาร HTML ตรงจากโปรเจกต์:

apidog export --project 123456 --format html --output ./docs.html

รันสถานการณ์การทดสอบใน CI และออกรายงานที่ไปป์ไลน์ของคุณสามารถอ่านได้:

apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"

คุณยังสามารถรันแบบออฟไลน์ทั้งหมดจากไฟล์คอลเลกชันที่ส่งออกได้ โดยไม่จำเป็นต้องมีโปรเจกต์หรือโทเค็น:

apidog run ./collection.apidog-cli.json

การอ้างอิงแฟล็กทั้งหมด รวมถึง --out-dir, -n/--iteration-count, -d/--iteration-data และ --env-var อยู่ใน คู่มือฉบับสมบูรณ์ของ Apidog CLI เอกสาร Apidog CLI อย่างเป็นทางการ ครอบคลุมการติดตั้งและคำสั่งทรัพยากรทุกอย่าง สำหรับการเปรียบเทียบ Runner ต่อ Runner ใน CI ดู Apidog CLI vs Newman และ Bruno CLI vs Apidog CLI.

เมื่อไหร่ควรเลือก Redocly CLI

เลือก Redocly CLI เมื่อสเปคคือแหล่งความจริงของคุณ และคุณต้องการกำกับดูแลมันในฐานะโค้ด

คุณต้องการ Linter จริงที่มีกฎที่กำหนดเอง คำสั่ง lint ของ Redocly และการกำหนดค่า redocly.yaml คือคุณสมบัติที่เป็นเอกลักษณ์: เลือกชุดกฎในตัวหรือเขียนเอง และบังคับใช้กฎการตั้งชื่อ, ฟิลด์ที่จำเป็น และสไตล์ขององค์กรในการ commit ทุกครั้ง ไม่มีสิ่งใดใน Apidog CLI ที่เทียบเท่าได้ หากงานคือการกำกับดูแลสไตล์ที่ทำงานบนเทอร์มินัล Redocly คือคำตอบ

คุณต้องการโอเพนซอร์สโดยไม่มีบัญชี CLI ทำงานทั้งหมดบนเครื่องของคุณหรือ CI runner ไม่มีการเข้าสู่ระบบ, ไม่มีโทเค็น, ไม่มีการเรียกเซิร์ฟเวอร์สำหรับ lint, bundle, split, หรือ build-docs สำหรับสภาพแวดล้อมที่ไม่มีการเชื่อมต่ออินเทอร์เน็ต (air-gapped) หรือกฎการจัดการข้อมูลที่เข้มงวด นั่นเป็นข้อกำหนดที่ Redocly ตอบสนองได้ และแพลตฟอร์ม CLI โดยทั่วไปมักจะไม่เป็นเช่นนั้น

คุณต้องการชุดเครื่องมือที่มีน้ำหนักเบาและเน้นเฉพาะ หากคุณต้องการเพียงแค่ lint, bundle, split, join และเอกสาร HTML จากเทอร์มินัล Redocly ทำสิ่งนั้นได้อย่างแม่นยำและไม่มีสิ่งอื่นใด คุณสามารถติดตั้งหรือรันผ่าน npx โดยไม่ต้องตั้งค่าอะไรเลย ชุดคำสั่งทั้งหมดอยู่ใน เอกสาร Redocly CLI และ หน้าแพ็กเกจ npm.

เมื่อไหร่ควรเลือก Apidog

เลือก Apidog เมื่อสเปคเป็นส่วนหนึ่งของวงจรชีวิตที่ใหญ่กว่าที่คุณไม่ต้องการประกอบจากเครื่องมือที่แยกต่างหาก

คุณต้องการการออกแบบ, การจำลอง, การทดสอบ และเอกสารในที่เดียว CLI นำเข้าสเปคของคุณ ส่งออกไฟล์ที่รวมกันอย่างสะอาดในเวอร์ชัน OpenAPI ที่คุณเลือก และรันสถานการณ์การทดสอบใน CI โปรเจกต์เดียวกันยังให้การออกแบบด้วยภาพ, เซิร์ฟเวอร์จำลอง และเอกสารที่เผยแพร่ โดยทั้งหมดใช้คำจำกัดความเดียวกัน คุณจะเลิกเชื่อมต่อ Linter, เครื่องมือจำลอง, Test Runner และ Doc Generator เข้าด้วยกัน

คุณต้องการการทดสอบในไปป์ไลน์พร้อมรายงานที่ใช้งานได้ apidog run สร้าง JUnit XML สำหรับแดชบอร์ด CI ของคุณ รวมถึงอาร์ติแฟกต์ HTML และ JSON และจะออกจากโปรแกรมโดยมีรหัสข้อผิดพลาดที่ไม่ใช่ศูนย์เมื่อการทดสอบล้มเหลว Redocly ไม่ได้รันการทดสอบเลย ดังนั้นหากการทดสอบ CI เป็นหนึ่งในรายการของคุณ นี่คือจุดที่ Apidog เหมาะสม รูปแบบใน การตรวจสอบ OpenAPI ใน CI จะจับคู่กับการรันการทดสอบในไปป์ไลน์เดียวกันได้อย่างเป็นธรรมชาติ

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

ดาวน์โหลด Apidog เพื่อลองทำตามได้ฟรี ไม่ต้องใช้บัตรเครดิต

พวกมันสามารถเสริมกันได้

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

เวิร์กโฟลว์ที่แข็งแกร่งจะรัน Redocly CLI (หรือ Spectral) เป็นเกตของ Lint ใน CI เพื่อบังคับใช้สไตล์ไกด์ของคุณในทุก Pull Request และใช้ Apidog สำหรับการออกแบบ, การจำลอง, การรันการทดสอบ และเอกสารที่เผยแพร่ Lint ในที่ที่ Lint ทำได้ดีที่สุด ด้วยชุดกฎโอเพนซอร์สในเทอร์มินัล จำลอง, ทดสอบ และทำเอกสารในที่ที่แพลตฟอร์มทำได้ดีที่สุด สเปคจะไหลเวียนระหว่างกัน: Lint ไฟล์ใน CI, นำเข้าไปใน Apidog สำหรับทุกอย่างที่ตามมา

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

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

Apidog CLI มีคำสั่ง lint ที่มีกฎที่กำหนดเองเหมือน Redocly หรือไม่?

ไม่มี Apidog ตรวจสอบความถูกต้องของโครงสร้างคำจำกัดความเมื่อคุณนำเข้า แต่ไม่มีคำสั่ง apidog lint และไม่มีวิธีสร้างกฎสไตล์ไกด์ที่กำหนดเองผ่าน CLI สำหรับการ lint ที่กำหนดค่าได้และเน้นโค้ดเป็นหลัก ให้ใช้ Redocly CLI หรือ Spectral

Redocly CLI สามารถรันการทดสอบ API ใน CI ได้หรือไม่?

ไม่ Redocly CLI ทำการ lint, bundle, split, join และสร้างเอกสาร มันไม่ทำการทดสอบ API และไม่โฮสต์เซิร์ฟเวอร์จำลอง สำหรับการรันการทดสอบแบบ headless พร้อมรายงาน JUnit และ HTML ให้ใช้ apidog run

Apidog เป็นโอเพนซอร์สเหมือน Redocly CLI หรือไม่?

ไม่ Redocly CLI และ Spectral เป็นโอเพนซอร์ส Apidog เป็นแบบฟรีเมียม: CLI สามารถติดตั้งได้ฟรีจาก npm แต่จะทำงานร่วมกับบัญชีและโปรเจกต์ Apidog แทนที่จะเป็นซอฟต์แวร์โอเพนซอร์สเต็มรูปแบบ

ฉันเคยใช้ swagger-cli สำหรับการตรวจสอบและรวมไฟล์ ฉันควรเปลี่ยนไปใช้อะไร?

ทั้งสองเครื่องมือครอบคลุมสิ่งนี้ Redocly CLI เป็นผู้สืบทอดที่ระบุไว้ของ swagger-cli ด้วย redocly lint (กำหนดค่ากฎ spec สำหรับการตรวจสอบความถูกต้องแบบธรรมดา) และ redocly bundle Apidog ครอบคลุมพื้นที่เดียวกันผ่าน apidog import (ตรวจสอบ) และ apidog export (รวมไฟล์ พร้อมการอัปเดตเวอร์ชัน OpenAPI ที่เลือกได้) และเพิ่มการจำลอง, การทดสอบ และเอกสารในพื้นที่ทำงานเดียวกัน