คำว่า “Swagger” มีความหมายที่แตกต่างกันถึงสามหรือสี่อย่าง ซึ่งเป็นส่วนหนึ่งของปัญหา บางครั้งคุณอาจหมายถึงรูปแบบข้อกำหนดแบบเปิด (open specification format) บางครั้งคุณอาจหมายถึง Swagger UI ซึ่งเป็นหน้าเว็บที่แสดงข้อกำหนดนั้นเป็นเอกสารที่คลิกได้ บางครั้งคุณอาจหมายถึง Swagger Editor ซึ่งเป็นพื้นที่ข้อความในเบราว์เซอร์ที่คุณเขียน YAML ด้วยตัวเอง และบางครั้งคุณอาจหมายถึง SwaggerHub ซึ่งเป็นผลิตภัณฑ์โฮสต์ที่รวมทุกอย่างเข้าด้วยกันสำหรับทีม เมื่อนักพัฒนาค้นหา “swagger alternative” ใน Google พวกเขามักจะไม่พอใจกับส่วนใดส่วนหนึ่งโดยเฉพาะ เช่น ตัวแก้ไขรู้สึกใช้งานยาก (clunky), UI เป็นแบบอ่านอย่างเดียว (read-only) หรือชุดเครื่องมือหยุดอยู่ที่การจัดทำเอกสารและปล่อยให้การทดสอบเป็นหน้าที่ของเครื่องมืออื่นโดยสิ้นเชิง
ช่องว่างสุดท้ายนี่แหละคือสิ่งที่สร้างปัญหา คุณออกแบบ API ใน Swagger Editor แสดงผลด้วย Swagger UI จากนั้นจึงเปิดแอปพลิเคชันที่แยกต่างหากโดยสิ้นเชิงเพื่อส่งคำขอจริง เขียนคำยืนยัน (assertions) และรันมันใน CI เครื่องมือสองอย่าง แหล่งความจริงสองแหล่ง และข้อกำหนดที่ค่อยๆ แตกต่างออกไปจากการทดสอบ หากคุณเคยเห็น เอกสาร Swagger และคอลเลกชัน Postman ของคุณค่อยๆ ไม่ตรงกัน คุณจะรู้ถึงความยุ่งยากนี้
เปรียบเทียบฉบับย่อ
| เครื่องมือ | ออกแบบ / แก้ไขสเปก | แสดงผลเอกสาร | ส่งคำขอ + ทดสอบ | โฮสต์สำหรับทีม | ใบอนุญาต |
|---|---|---|---|---|---|
| Swagger (UI / Editor / Hub) | ใช่ | ใช่ | ไม่ใช่ (UI เป็นเพียงการทดลองเท่านั้น) | SwaggerHub (แบบชำระเงิน) | Apache 2.0 / เชิงพาณิชย์ |
| Apidog | ใช่ (แบบภาพ) | ใช่ | ใช่ (รันเนอร์ทดสอบเต็มรูปแบบ + CLI) | ใช่ | แบบฟรี + แบบชำระเงิน |
| Stoplight | ใช่ (แบบภาพ) | ใช่ | จำกัด | ใช่ | แบบฟรี + แบบชำระเงิน |
| Redocly | Editor + CLI | ใช่ (Redoc) | ไม่ใช่ | ใช่ | แบบฟรี + แบบชำระเงิน |
| Scalar | Editor | ใช่ | ไคลเอนต์ API ในตัว | ใช่ | โอเพนซอร์ส + แบบชำระเงิน |
| Postman | นำเข้าสเปก | ใช่ | ใช่ | ใช่ | แบบฟรี + แบบชำระเงิน |
| Insomnia | นำเข้าสเปก | จำกัด | ใช่ | ใช่ | แบบฟรี + แบบชำระเงิน |
| Bump.sh | ไม่ใช่ (ใช้สเปกเท่านั้น) | ใช่ | ไม่ใช่ | ใช่ | แบบฟรี + แบบชำระเงิน |
คอลัมน์ที่สำคัญที่สุดขึ้นอยู่กับความต้องการของคุณ หากการแสดงผลเอกสารคือทั้งหมดของงาน Redocly, Scalar และ Bump.sh ถือว่าแข็งแกร่ง หากคุณต้องการทั้งการออกแบบและการทดสอบในที่เดียว ตัวเลือกก็จะแคบลงอย่างรวดเร็ว
Swagger ทำอะไรได้ดี (และหยุดอยู่ตรงไหน)
มาเริ่มกันที่ความจริงใจ ข้อกำหนด OpenAPI ซึ่งพัฒนามาจากข้อกำหนด Swagger ดั้งเดิม เป็นมาตรฐานที่เครื่องมือเกือบทุกชนิดในรายการนี้สามารถอ่านและเขียนได้ Swagger UI เป็นเครื่องมือแสดงผลเอกสาร API ที่เป็นที่รู้จักมากที่สุดในโลก เป็นโอเพนซอร์สภายใต้ Apache 2.0 และปุ่ม “Try it out” ได้ช่วยให้นักพัฒนาจำนวนมากได้รู้จักการเรียก API จริงมากกว่าฟังก์ชันอื่นใด Swagger Editor ช่วยให้คุณสามารถตรวจสอบความถูกต้องของสเปกได้ทันทีที่คุณพิมพ์ สิ่งเหล่านี้ยังคงอยู่และคุณไม่ควรทิ้งมันไปเพียงเพื่อความแปลกใหม่
จุดที่มันหยุดคือวงจรการทำงาน “Try it out” ของ Swagger UI จะส่งคำขอเดียวจากเบราว์เซอร์ ซึ่งเป็นเพียงการสาธิต ไม่ใช่ชุดเครื่องมือทดสอบ ไม่มีเอ็นจินการยืนยัน (assertion engine) ไม่มีสถานการณ์การทดสอบ (test scenarios) ไม่มีการจัดการสภาพแวดล้อม (environment management) และไม่มี CLI runner สำหรับ CI Swagger Editor เป็นเพียงช่องข้อความ ดังนั้นงานออกแบบของคุณคือการเขียน YAML ด้วยมือ โดยไม่มีตัวสร้างสคีมาแบบภาพ (visual schema builder) SwaggerHub เพิ่มคุณสมบัติการทำงานร่วมกันและการโฮสต์ แต่คิดค่าใช้จ่ายต่อผู้ใช้ และแม้แต่การทดสอบก็ไม่ใช่หน้าที่ของมัน ผลลัพธ์ที่ได้คือชุดเครื่องมือสำหรับจัดทำเอกสาร ไม่ใช่ชุดเครื่องมือสำหรับการพัฒนา ทางเลือกอื่น ๆ ด้านล่างนี้เป็นคำตอบของคำถามที่ว่า “ฉันควรจะเพิ่มอะไรเข้าไป หรือใช้อะไรแทน เพื่อให้ก้าวข้ามแค่เรื่องเอกสารไปได้?”
หากคุณยังคงเรียนรู้เกี่ยวกับรูปแบบนี้อยู่ ข้อมูลเบื้องต้นเกี่ยวกับ Swagger และ OpenAPI จะเป็นจุดเริ่มต้นที่ดีกว่าการเปรียบเทียบนี้
1. Apidog: ออกแบบและทดสอบสเปกเดียวกันในที่เดียว
Apidog สร้างขึ้นจากแนวคิดที่ว่า สเปก, ม็อก (mock), การทดสอบ และเอกสาร ไม่ควรเป็นไฟล์ที่แยกจากกันในเครื่องมือที่แตกต่างกัน คุณออกแบบ endpoint ใน Visual Editor ที่เขียน OpenAPI ที่ถูกต้องเบื้องหลัง และในทันทีที่สคีมาถูกสร้างขึ้น คุณจะได้รับสามสิ่งฟรี: หน้าเอกสารแบบอินเทอร์แอคทีฟ, เซิร์ฟเวอร์จำลอง (mock server) ที่ส่งคืนข้อมูลตามรูปแบบสคีมา และคำขอที่คุณสามารถส่งและยืนยันได้จริง
ส่วนสุดท้ายนี้คือสิ่งที่ทำให้ Apidog แตกต่างจากเครื่องมือเอกสารทั่วไป Swagger UI แสดง endpoint ให้คุณเห็น แต่ Apidog ช่วยให้คุณสร้างสถานการณ์การทดสอบ เชื่อมโยงคำขอ ดึงโทเค็นจากคำตอบหนึ่งและป้อนไปยังคำขอถัดไป และยืนยันรหัสสถานะและฟิลด์ JSON โดยไม่ต้องเขียนสคริปต์ เมื่อการออกแบบเปลี่ยนแปลง การทดสอบจะอ้างอิงจากข้อกำหนดเดียวกัน ทำให้การทดสอบไม่ล้าสมัยโดยไม่รู้ตัว คุณสามารถสร้างชุด คอลเลกชันการทดสอบทั้งหมดได้โดยตรงจาก OpenAPI spec แทนที่จะสร้างด้วยมือ
สำหรับฝั่ง CI มี Command-line runner ที่เผยแพร่เป็นแพ็คเกจ 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,cli) รันเนอร์จะออกด้วยรหัสสถานะที่สะอาด ดังนั้นการยืนยันที่ล้มเหลวจะทำให้ pipeline เป็นสีแดง หากคุณต้องการดูแฟล็กทั้งหมด ให้รัน apidog run --help; คำแนะนำฉบับเต็มอยู่ใน คู่มือ Apidog CLI และ CI automation
เหมาะสำหรับ: ทีมที่เบื่อหน่ายกับการออกแบบในเครื่องมือหนึ่งและการทดสอบในเครื่องมืออื่น ไม่เหมาะสำหรับ: หากสิ่งที่คุณต้องการคือหน้าเอกสารแบบสแตติกสำหรับสเปกที่เสร็จสมบูรณ์ Apidog อาจเป็นเครื่องมือที่เกินความจำเป็น ดาวน์โหลด Apidog หากปัญหาของคุณคือการทับซ้อนกันระหว่างการออกแบบและการทดสอบ
2. Stoplight: การออกแบบที่เน้นสเปกเป็นหลักพร้อมการกำกับดูแลที่แข็งแกร่ง
Stoplight เป็นคู่แข่งที่ใกล้เคียงที่สุดกับ Swagger Editor สำหรับผู้ที่ต้องการออกแบบ API ด้วยภาพแทนการพิมพ์ YAML ตัวแก้ไข Studio ของ Stoplight ให้มุมมองเอกสาร OpenAPI ในรูปแบบฟอร์ม และ Spectral ซึ่งเป็นเอนจิน linting แบบโอเพนซอร์สของ Stoplight ถือเป็นเครื่องมือที่ดีที่สุดสำหรับการบังคับใช้ API style guides หากองค์กรของคุณให้ความสำคัญกับการตั้งชื่อที่สอดคล้องกัน คำอธิบายที่จำเป็น และกฎการออกแบบในสเปกจำนวนมาก Spectral คือเหตุผลที่คุณควรพิจารณา Stoplight
สิ่งที่ทำได้ดี: การออกแบบด้วยภาพ, การจำลอง (mocking) จากสเปก, เอกสารที่โฮสต์ และการกำกับดูแลในระดับใหญ่ สิ่งที่ทำได้น้อยลง: Stoplight เป็นแพลตฟอร์มสำหรับการออกแบบและจัดทำเอกสาร ไม่ใช่รันเนอร์ทดสอบที่สมบูรณ์ คุณสามารถทดสอบ mock ได้ แต่สำหรับการทดสอบฟังก์ชันการทำงานที่จริงจังด้วยสถานการณ์ที่เชื่อมโยงกันและการยืนยัน CI คุณจะต้องใช้เครื่องมืออื่น ทีมที่ลงทุนใน Stoplight อยู่แล้วบางครั้งก็จับคู่กับแอปทดสอบที่แยกต่างหาก ซึ่งทำให้คุณกลับไปสู่การใช้สองเครื่องมือ หากคุณกำลังพิจารณาที่จะย้าย บันทึกการย้ายจาก Stoplight ไปยัง Apidog จะครอบคลุมถึงสิ่งที่สามารถถ่ายโอนได้
เหมาะสำหรับ: ทีมที่เน้นการออกแบบและมีข้อกำหนดด้านการกำกับดูแลที่เข้มงวด ไม่เหมาะสำหรับ: หากคุณต้องการให้เครื่องมือเดียวกันนี้รันการทดสอบของคุณด้วย
3. Redocly: เอกสารสแตติกที่สะอาดที่สุด พร้อมด้วย CLI จริง
Redocly สร้างขึ้นบน Redoc ซึ่งเป็นเครื่องมือแสดงผลแบบโอเพนซอร์สที่สร้างหน้าอ้างอิง API แบบสามพาเนลยาวๆ ที่คุณเคยเห็นในพอร์ทัลนักพัฒนาจำนวนมาก ผลลัพธ์ที่ได้สะอาดตา รวดเร็ว และเป็นการอัปเกรดรูปลักษณ์ที่ชัดเจนกว่า Swagger UI เริ่มต้น Redocly บริษัทเพิ่มพอร์ทัลที่โฮสต์ไว้ การจัดการเวอร์ชัน และ CLI ที่ใช้งานง่ายสำหรับนักพัฒนา ซึ่งสามารถรวม ตรวจสอบ (lint) และดูตัวอย่างสเปกของคุณจากเทอร์มินัลได้:
npx @redocly/cli lint openapi.yaml
npx @redocly/cli build-docs openapi.yaml -o docs.html
สิ่งที่ทำได้ดี: การจัดทำเอกสาร หากเป้าหมายของคุณคือการเผยแพร่เอกสารอ้างอิง API ที่สวยงามและมีประสิทธิภาพจากไฟล์ OpenAPI Redocly เป็นหนึ่งในตัวเลือกที่แข็งแกร่งที่สุด และคำสั่ง lint จะช่วยตรวจจับปัญหาสเปกตั้งแต่เนิ่นๆ สิ่งที่ทำไม่ได้: ส่งคำขอหรือรันการทดสอบ มันเป็นผลิตภัณฑ์ที่เน้นเอกสารและเครื่องมือสเปกอย่างชัดเจน สำหรับข้อมูลเชิงลึกเพิ่มเติมว่ามันดีเด่นตรงไหนและมีข้อจำกัดอะไรบ้าง โปรดดู การรวบรวมทางเลือก Redocly
เหมาะสำหรับ: ทีมที่ต้องการเอกสารอ้างอิงที่สวยงามและมีการควบคุมเวอร์ชันเป็นอันดับแรก ไม่เหมาะสำหรับ: ผู้ที่คาดหวังว่าทางเลือกนี้จะครอบคลุมถึงการทดสอบด้วย
4. Scalar: เอกสารโอเพนซอร์สพร้อมไคลเอนต์ API ในตัว
Scalar เป็นเครื่องมือโอเพนซอร์สใหม่ที่นักพัฒนาจำนวนมากเลือกใช้เมื่อ Swagger UI รู้สึกว่าล้าสมัย มันแสดงผล OpenAPI spec เป็นหน้าเอกสารที่สะอาดตาและสามารถค้นหาได้ และแตกต่างจาก Swagger UI ตรงที่มาพร้อมกับไคลเอนต์ API จริงที่สร้างในเอกสาร ทำให้ประสบการณ์ “ลองใช้” ใกล้เคียงกับเครื่องมือส่งคำขอขนาดเล็กมากกว่าปุ่มเดโมแบบครั้งเดียว เนื่องจากแกนหลักได้รับอนุญาตภายใต้ MIT คุณจึงสามารถโฮสต์เองและปรับแต่งธีมได้อย่างอิสระ
สิ่งที่ทำได้ดี: เอกสารโอเพนซอร์สที่น่าสนใจพร้อมไคลเอนต์แบบโต้ตอบ และมีท่าทีที่เปิดกว้างให้ใช้งานฟรี ข้อจำกัด: ไม่ใช่แพลตฟอร์มสถานการณ์การทดสอบที่มีการยืนยัน (assertions), สภาพแวดล้อม (environments) และ CI runner ไคลเอนต์ในตัวมีไว้สำหรับการสำรวจ ไม่ใช่การทดสอบรีเกรสชันอัตโนมัติ การเปรียบเทียบทางเลือกของ Scalar จะแสดงข้อดีข้อเสียเมื่อเทียบกับแพลตฟอร์มที่ใหญ่กว่า
เหมาะสำหรับ: โครงการโอเพนซอร์สและทีมอิสระที่ต้องการเอกสารที่ดูดีและควบคุมได้ ไม่เหมาะสำหรับ: ทีมที่ต้องการการทดสอบอัตโนมัติใน pipeline
5. Postman: เครื่องมือสำหรับส่งคำขอที่ทีมส่วนใหญ่มีอยู่แล้ว
Postman ไม่ใช่เครื่องมือที่เน้นเอกสารเป็นอันดับแรก แต่ปรากฏขึ้นในการค้นหา “swagger alternative” ทุกครั้ง เนื่องจากมีหลายทีมที่ใช้งานมันอยู่แล้ว คุณสามารถนำเข้า OpenAPI spec, ได้คอลเลกชันของคำขอ, ส่งคำขอเหล่านั้น, เขียนการทดสอบด้วย JavaScript โดยใช้ pm.test API และรันทั้งหมดใน CI ด้วย Newman สำหรับการส่งคำขอและการเขียนสคริปต์อย่างเดียว มันเป็นเครื่องมือที่สมบูรณ์และเป็นที่เข้าใจอย่างกว้างขวาง
สิ่งที่ทำได้ดี: คำขอแบบเฉพาะกิจ (ad-hoc requests), ความยืดหยุ่นในการเขียนสคริปต์, ระบบนิเวศขนาดใหญ่ และพื้นที่ทำงานของทีม จุดที่เป็นปัญหา: สเปกและคอลเลกชันเป็นสิ่งแยกต่างหาก ดังนั้นการนำเข้าไฟล์ OpenAPI ที่อัปเดตจะไม่ผสานรวมกับการแก้ไขที่คุณทำกับคอลเลกชันอย่างสมบูรณ์ และทั้งสองก็ค่อยๆ แยกห่างกันออกไป ราคาที่เพิ่มขึ้นยังผลักดันให้ทีมมองหาทางเลือกอื่นเมื่อจำนวนผู้ใช้เพิ่มขึ้น หากค่าใช้จ่ายหรือความไม่ตรงกันเป็นปัจจัยกระตุ้นของคุณ ทางเลือก Postman สำหรับการทดสอบ API คือบทความที่เกี่ยวข้อง
เหมาะสำหรับ: ทีมที่ต้องการอิสระในการเขียนสคริปต์สูงสุด และมีทักษะการใช้ Postman อยู่แล้ว ไม่เหมาะสำหรับ: ทีมที่ต้องการให้สเปกและการทดสอบเป็นแหล่งความจริงที่ซิงโครไนซ์กันเพียงหนึ่งเดียว
6. Insomnia: ไคลเอนต์สำหรับส่งคำขอที่กระชับและเป็นโอเพนคอร์
Insomnia เป็นน้องเล็กที่เบากว่าและใช้งานง่ายกว่า Postman ในการใช้คีย์บอร์ด มันสามารถนำเข้า OpenAPI และ GraphQL, ส่งคำขอ, และรองรับมุมมองการออกแบบสำหรับการแก้ไขสเปก พร้อมกับ Inso CLI สำหรับการรันชุดการทดสอบแบบอัตโนมัติ นักพัฒนาที่รู้สึกว่า Postman หนักเกินไปมักจะชื่นชอบความเร็วและอินเทอร์เฟซที่สะอาดตาของ Insomnia และแกนหลักยังมีมรดกโอเพนซอร์สที่ดึงดูดผู้ที่ระมัดระวังเรื่องการผูกขาดจากผู้ขาย (vendor lock-in)
สิ่งที่ทำได้ดี: การทำงานกับคำขอที่รวดเร็ว, รองรับ GraphQL และมีขนาดไฟล์ที่เล็กกว่า ข้อควรระวัง: การแสดงผลเอกสารบางกว่าเครื่องมือเอกสารเฉพาะด้านที่กล่าวมาข้างต้น และ Insomnia มีการออกเวอร์ชันที่ไม่ราบรื่นนักเกี่ยวกับข้อกำหนดบัญชีและการจัดเก็บข้อมูล ซึ่งทำให้ผู้ใช้บางรายต้องพิจารณาทางเลือกอื่น มันใกล้เคียงกับ “ไคลเอนต์สำหรับส่งคำขอที่มีมุมมองการออกแบบ” มากกว่า “แพลตฟอร์มการออกแบบและทดสอบเต็มรูปแบบ” สำหรับการดูเชิงปฏิบัติ โปรดดู วิธีใช้ Insomnia เพื่อทดสอบ API
เหมาะสำหรับ: นักพัฒนาที่ต้องการไคลเอนต์สำหรับส่งคำขอที่รวดเร็ว ใช้งานง่าย และไม่ต้องการเอกสารที่โฮสต์ไว้มากมาย ไม่เหมาะสำหรับ: ทีมที่ต้องการการออกแบบ, เอกสาร และการทดสอบที่เป็นหนึ่งเดียวกัน
7. Bump.sh: การจัดทำเอกสารและการติดตามการเปลี่ยนแปลง ที่ทำได้ในแบบเดียว
Bump.sh มุ่งเน้นทำสิ่งเดียวโดยเจตนา: เปลี่ยนไฟล์ OpenAPI หรือ AsyncAPI ให้เป็นเอกสารที่โฮสต์ และติดตามทุกการเปลี่ยนแปลงของสเปกนั้นเมื่อเวลาผ่านไป เมื่อคุณพุชสเปกเวอร์ชันใหม่ Bump.sh จะสร้าง changelog และ diff ที่มนุษย์อ่านได้ ซึ่งมีประโยชน์อย่างแท้จริงสำหรับการสื่อสารการเปลี่ยนแปลงที่ส่งผลกระทบ (breaking changes) ให้กับผู้ใช้ API
สิ่งที่ทำได้ดี: เอกสารที่โฮสต์อย่างสะอาดตาและการติดตามการเปลี่ยนแปลง API ระดับเฟิร์สคลาส รวมถึงสำหรับสเปก AsyncAPI ที่ขับเคลื่อนด้วยเหตุการณ์ ซึ่งเครื่องมือจำนวนมากละเลย สิ่งที่ไม่ได้ทำโดยเจตนา: ไม่แก้ไขสเปก, ไม่ส่งคำขอ หรือรันการทดสอบ มันจะใช้สเปกที่คุณสร้างจากที่อื่น การเน้นเพียงจุดเดียวนั้นถือเป็นคุณสมบัติที่ดีหากเอกสารและ changelog คือสิ่งที่คุณต้องการ และเป็นข้อเสียเปรียบอย่างยิ่งหากคุณต้องการการทดสอบ หากคุณสนใจการพัฒนาสเปก การแจกแจง การเปลี่ยนแปลงระหว่าง OpenAPI 3.0, 3.1 และ 3.2 เข้ากันได้ดีกับเวิร์กโฟลว์การติดตามการเปลี่ยนแปลง
เหมาะสำหรับ: ทีมที่เผยแพร่สเปกและต้องการเอกสารที่สวยงามพร้อม changelog ที่น่าเชื่อถือ ไม่เหมาะสำหรับ: ผู้ที่ต้องการเครื่องมือออกแบบและทดสอบแบบครบวงจร
วิธีการเลือก
จัดเรียงเครื่องมือทั้งเจ็ดตามงานที่คุณต้องการทำให้สำเร็จ
- เฉพาะเอกสารเท่านั้น จากสเปกที่เสร็จสมบูรณ์ Redocly, Scalar และ Bump.sh สะอาดตาที่สุด เลือก Redocly เพื่อความประณีตและ CLI, Scalar เพื่อการควบคุมแบบโอเพนซอร์ส, Bump.sh สำหรับการติดตามการเปลี่ยนแปลง
- การออกแบบสเปกด้วยภาพพร้อมการกำกับดูแล Stoplight โดยเฉพาะอย่างยิ่งหากการ linting ด้วย Spectral มีความสำคัญต่อองค์กรขนาดใหญ่
- การส่งคำขอและการเขียนสคริปต์การทดสอบ Postman หากคุณต้องการอิสระในการเขียนสคริปต์สูงสุด, Insomnia หากคุณต้องการเครื่องมือที่เบากว่า
- การออกแบบและการทดสอบในแหล่งความจริงเดียว Apidog เนื่องจากสเปก, ม็อก, การทดสอบ และเอกสารใช้ข้อกำหนดเดียวกัน และการทดสอบเดียวกันนี้จะรันใน CI ผ่าน
apidog-cli
การตรวจสอบความรู้สึกที่ได้ผล: ลองนับแท็บของคุณ หากการออกแบบ, การจำลอง, การจัดทำเอกสาร และการทดสอบ API หนึ่งตัวหมายถึงการเปิดเครื่องมือสี่ตัวที่แตกต่างกัน ความไม่ตรงกันระหว่างเครื่องมือเหล่านั้นคือค่าใช้จ่ายที่เกิดขึ้นซ้ำๆ ไม่ใช่การตั้งค่าครั้งเดียว เหตุผลที่คำว่า “swagger alternative” เป็นการค้นหาที่พบบ่อยนั้นเป็นเพราะ Swagger ทำหน้าที่ของมันได้ดีแล้วก็หยุดลง และเครื่องมือเสริมต่างๆ ก็แทบจะไม่สื่อสารกัน การรวมวงจรการออกแบบและการทดสอบเข้าด้วยกันคือจุดที่ประหยัดเวลาได้มากที่สุด
ไม่ว่าคุณจะเลือกอะไร ให้ยึดสเปกเป็นศูนย์กลาง ตรวจสอบความถูกต้อง (lint), ยืนยันความถูกต้อง (validate) และถือว่าเป็นสัญญา ไม่ใช่สิ่งที่คุณสร้างขึ้นมาใหม่จากโค้ด หลักการ การออกแบบ API ที่แข็งแกร่ง และนิสัยการใช้งาน OpenAPI validator จริงๆ จะอยู่ได้นานกว่าเครื่องมือใดๆ ในรายการนี้
คำถามที่พบบ่อย (FAQ)
Swagger เหมือนกับ OpenAPI หรือไม่? ไม่เชิงทีเดียว OpenAPI คือมาตรฐานของข้อกำหนด; Swagger คือชื่อดั้งเดิมและกลุ่มเครื่องมือ (Swagger UI, Editor และ SwaggerHub) ที่ SmartBear สร้างขึ้นรอบๆ มัน เมื่อผู้คนพูดว่า “swagger file” พวกเขามักจะหมายถึงเอกสาร OpenAPI เสมอ รูปแบบนี้มีการใช้ร่วมกัน ดังนั้นเครื่องมือทุกตัวในที่นี้จึงอ่านสเปกเดียวกัน
ทางเลือกฟรีที่ดีที่สุดสำหรับ Swagger คืออะไร? สำหรับการจัดทำเอกสาร Scalar เป็นโอเพนซอร์สและสามารถโฮสต์เองได้ฟรี สำหรับการออกแบบและการทดสอบในที่เดียว Apidog มีแผนฟรีที่ครอบคลุมนักพัฒนาเดี่ยวและโปรเจกต์ขนาดเล็ก Swagger UI และ Swagger Editor เองก็ฟรีและเป็นโอเพนซอร์สเช่นกัน ดังนั้น "ฟรี" จึงไม่ค่อยเป็นปัจจัยในการตัดสินใจ คำถามที่แท้จริงคือเครื่องมือครอบคลุมวงจรการทำงานได้มากน้อยเพียงใด
มีเครื่องมือใดในกลุ่มนี้ที่สามารถทั้งออกแบบสเปกและรันการทดสอบได้บ้าง? นี่คือจุดแบ่ง เครื่องมือเอกสารส่วนใหญ่ (Redocly, Scalar, Bump.sh) ทำได้แค่แสดงผล เครื่องมือส่งคำขอส่วนใหญ่ (Postman, Insomnia) ทำได้แค่ทดสอบ โดยมีสเปกนำเข้าเป็นสิ่งแยกต่างหาก Apidog เป็นตัวเลือกที่ออกแบบมาเพื่อให้คำจำกัดความ OpenAPI เดียวกันนี้ใช้ในการขับเคลื่อนการออกแบบ, ม็อก และสถานการณ์การทดสอบ และ apidog-cli จะรันการทดสอบเหล่านั้นใน CI
ฉันจำเป็นต้องเลิกใช้ Swagger UI เพื่อใช้เครื่องมือเหล่านี้หรือไม่? ไม่จำเป็น OpenAPI spec สามารถพกพาได้ คุณสามารถเก็บ Swagger UI ไว้สำหรับเอกสารสาธารณะ และใช้เครื่องมืออื่นสำหรับการออกแบบหรือการทดสอบ หรือนำเข้าสเปกที่มีอยู่ของคุณไปยังแพลตฟอร์มใหม่และรักษาแหล่งความจริงเดียว เนื่องจากรูปแบบเป็นมาตรฐาน ต้นทุนในการเปลี่ยนส่วนใหญ่เกี่ยวกับพฤติกรรมการทำงาน ไม่ใช่การแปลงไฟล์ คุณยังสามารถ นำเข้าไฟล์ Swagger หรือ OpenAPI และสร้างคำขอที่สามารถรันได้ ภายในไม่กี่นาที
ทางเลือกใดดีที่สุดสำหรับ CI/CD pipelines? คุณต้องการเครื่องมือที่มีรันเนอร์ทดสอบจริงและ CLI ที่ส่งคืนรหัสออกที่ถูกต้อง Apidog มี apidog-cli สำหรับสิ่งนี้; Postman มี Newman และ Insomnia มี Inso เครื่องมือเอกสารล้วนๆ เช่น Redocly และ Bump.sh ไม่ได้ถูกสร้างมาเพื่อการทดสอบฟังก์ชันการทำงานใน pipeline แม้ว่า CLI ของ Redocly จะมีประโยชน์สำหรับการ linting สเปกในขั้นตอน pre-commit หรือ CI ก็ตาม