หากคุณรัน API tests จาก inso ซึ่งเป็น CLI ของ Insomnia ของ Kong และคุณกำลังคิดที่จะเปลี่ยนแปลง คู่มือนี้จะพาคุณไปตลอดเส้นทาง คุณจะได้เห็นวิธีเอ็กซ์พอร์ตสเปคและชุดทดสอบของคุณออกจาก Insomnia นำเข้าสู่ Apidog และเขียนคำสั่ง inso run ของคุณใหม่เป็นคำสั่ง apidog run มีตารางเปรียบเทียบคำสั่งก่อน/หลัง เพื่อให้คุณสามารถจับคู่สคริปต์ CI ที่มีอยู่ของคุณได้ทีละบรรทัด
ทำไมทีมถึงย้ายจาก inso ไปยัง Apidog CLI
inso เป็นเครื่องมือที่แข็งแกร่ง มันนำการเรียกใช้งานรีเควสต์, การลินต์ Spectral และการทดสอบหน่วย (unit tests) มาสู่เทอร์มินัล และอ่านจากไดเรกทอรี .insomnia ที่สร้างโดย Git Sync ของ Insomnia หากเวิร์กโฟลว์นั้นเหมาะสมกับคุณ ก็ไม่มีกฎที่บอกว่าคุณต้องย้ายออกไป
ปัญหาโดยทั่วไปมักจะเริ่มต้นที่แอป Insomnia ไม่ใช่ CLI มีสองสิ่งที่เป็นแรงผลักดันหลักในการค้นหาการโยกย้าย:
- บัญชีคลาวด์ที่จำเป็น Insomnia 8 ที่เปิดตัวในปี 2023 ได้นำเสนอการเข้าสู่ระบบ/บัญชีคลาวด์ที่บังคับ ซึ่งทำให้หลายทีมไม่ทันตั้งตัว นักพัฒนาจำนวนมากต้องการไคลเอนต์แบบ Local-first แต่กลับเจอหน้าจอให้ลงชื่อเข้าใช้แทน
- การสูญหายของข้อมูลและความยุ่งยากในการโยกย้าย ผู้ใช้บางรายพบกับการสูญหายของข้อมูลและปัญหาการโยกย้ายในช่วงการเปลี่ยนผ่านนั้น หากคุณเคยประสบเหตุการณ์เช่นนั้น คุณจะรู้ถึงความเสียหายอยู่แล้ว หากคุณกำลังกู้คืนจากเหตุการณ์ดังกล่าวอยู่ตอนนี้ คู่มือเหล่านี้จะช่วยคุณได้: การกู้คืนและส่งออกข้อมูล Insomnia และคู่มือเชิงลึก การกู้คืนข้อมูลและการโยกย้ายจาก Insomnia 8
อีกเหตุผลหนึ่งคือการรวมศูนย์ ด้วย inso, CLI เป็นส่วนหนึ่งของสแต็ค: Insomnia สำหรับรีเควสต์, Spectral สำหรับการลินต์, เครื่องมือแยกต่างหากสำหรับการจำลองและเอกสาร Apidog รวมการออกแบบ, การดีบัก, การทดสอบ, การจำลอง และเอกสารประกอบไว้ในแพลตฟอร์มเดียว และ CLI รันส่วนการทดสอบของแพลตฟอร์มนั้น มีชิ้นส่วนที่เคลื่อนที่น้อยลง และมีแหล่งข้อมูลเดียวที่เชื่อถือได้
หากคุณต้องการข้อมูลเพิ่มเติมก่อนตัดสินใจ Apidog vs Insomnia และ การเลือกระหว่าง Insomnia และ Apidog จะอธิบายข้อดีข้อเสียของแอปพลิเคชันเต็มรูปแบบ ไม่ใช่เฉพาะ CLI
ก่อนที่คุณจะเริ่ม: สิ่งที่จะย้ายและสิ่งที่จะไม่ย้าย
กำหนดความคาดหวังล่วงหน้า เพื่อไม่ให้มีอะไรต้องประหลาดใจระหว่างการโยกย้าย
| สินทรัพย์ใน Insomnia | ย้ายไป Apidog หรือไม่? | วิธีการ |
|---|---|---|
| OpenAPI / เอกสารการออกแบบ | ใช่ | ส่งออกเป็น YAML/JSON, นำเข้าสู่ Apidog |
| ชุดคอลเลกชันคำขอ | ใช่ | ส่งออก แล้วนำเข้า |
| สภาพแวดล้อมและตัวแปร | ใช่ | สร้างขึ้นใหม่เป็นสภาพแวดล้อม Apidog |
ชุดทดสอบหน่วย (inso run test) |
บางส่วน | สร้างใหม่เป็นสถานการณ์ทดสอบ Apidog |
การกำหนดค่า Spectral lint (inso lint spec) |
ไม่มี 1:1 | ดูหมายเหตุจากใจจริงด้านล่าง |
หมายเหตุจากใจจริง: inso lint spec รัน Spectral ซึ่งเป็น OpenAPI linter ของ Stoplight และนั่นเป็นจุดแข็งที่แท้จริง Apidog CLI ไม่ได้มาพร้อมกับคำสั่ง linter, style-guide, split, join หรือ bundle สำหรับสเปคแบบสแตนด์อโลน Apidog จะตรวจสอบความถูกต้องของสเปคของคุณเมื่อคุณนำเข้า ดังนั้นปัญหาโครงสร้างจะปรากฏขึ้นในขณะนำเข้า แต่หากไปป์ไลน์ของคุณขึ้นอยู่กับชุดกฎ Spectral ที่กำหนดเองเป็นเกณฑ์ ให้เก็บ Spectral ไว้ใน CI ควบคู่ไปกับ Apidog อย่าคาดหวัง apidog lint มันไม่มีอยู่จริง และการแสร้งทำเป็นว่ามีจะทำให้คุณเดือดร้อนในภายหลังเท่านั้น
ขั้นตอนที่ 1: ส่งออกสเปคและชุดทดสอบของคุณจาก Insomnia
inso สามารถเขียนเอกสารการออกแบบของคุณลงในไฟล์ได้โดยตรง สเปคถูกอ้างอิงตามชื่อ ซึ่งเป็นชื่อเดียวกับที่คุณเห็นในแอป Insomnia:
# ส่งออกเอกสารการออกแบบ OpenAPI ไปยังไฟล์ YAML
inso export spec "My API Design" --output my-api.yaml
หาก inso หาข้อมูลของคุณไม่พบ ให้ระบุแหล่งที่ถูกต้อง โดยปกติแล้วจะอ่านจากไดเรกทอรี .insomnia ในไดเรกทอรีการทำงานปัจจุบัน หรือไดเรกทอรีข้อมูลของแอป Insomnia สามารถกำหนดทับได้ด้วย --workingDir หรือ --src:
inso export spec "My API Design" --workingDir ./design --output my-api.yaml
สำหรับชุดคอลเลกชันคำขอและสิ่งใดก็ตามที่ inso ไม่สามารถส่งออกได้อย่างสะอาดตา ให้ใช้แอป Insomnia เอง: เปิดแอป เลือกพื้นที่ทำงานของคุณ แล้วใช้ Export เพื่อสร้างไฟล์ OpenAPI หรือ Insomnia v4 เก็บทั้งเอกสารการออกแบบและการส่งออกคอลเลกชันไว้ คุณจะต้องนำเข้าแยกกัน
หากคุณกำลังอยู่ในช่วงการกู้คืนและแอปไม่ให้ความร่วมมือ คู่มือการส่งออกและการกู้คืน จะครอบคลุมถึงการนำข้อมูลออกมาเมื่อ Git Sync หรือบัญชีคลาวด์กำลังสร้างปัญหาให้คุณ
ขั้นตอนที่ 2: นำเข้าสู่ Apidog
เปิด Apidog สร้างโปรเจกต์ และนำเข้าไฟล์ YAML หรือ JSON ที่คุณเพิ่งส่งออกไป Apidog อ่าน OpenAPI ได้โดยตรง ดังนั้นเอนด์พอยต์, สกีมา และข้อมูลตัวอย่างของคุณจะถูกนำมาใช้เป็นทรัพยากรที่มีโครงสร้างที่คุณสามารถแก้ไข, จำลอง และทดสอบได้
คุณยังสามารถนำเข้าจาก CLI ซึ่งเป็นส่วนหนึ่งของการตั้งค่าอัตโนมัติ ซึ่งมีประโยชน์เมื่อคุณเขียนสคริปต์สำหรับการย้ายทีมทั้งทีม แทนที่จะคลิกผ่าน UI Apidog นำเข้า OpenAPI และจัดการเอนด์พอยต์, สกีมา, สภาพแวดล้อม, สาขา และคำขอรวม (merge requests) ในรูปแบบโค้ดจากเทอร์มินัล โดยตรวจสอบสิทธิ์ผ่านการเข้าสู่ระบบหรือโทเค็นการเข้าถึง หากคุณกำลังตั้งค่า CLI เป็นครั้งแรก คู่มือการติดตั้ง Apidog CLI และ คู่มือ CLI ฉบับสมบูรณ์ จะครอบคลุมการตั้งค่าและขั้นตอนการตรวจสอบสิทธิ์
เมื่อนำเข้า Apidog จะตรวจสอบความถูกต้องของสเปค หาก OpenAPI ของคุณมีปัญหาโครงสร้าง คุณจะพบตอนนี้เลย แทนที่จะเป็นตอนรันไทม์ นี่คือสิ่งที่ใกล้เคียงที่สุดกับ inso lint spec โดยมีความแตกต่างที่ควรกล่าวซ้ำ: มันคือการตรวจสอบความถูกต้อง ไม่ใช่ชุดกฎ Spectral ที่สามารถกำหนดค่าได้
ขั้นตอนที่ 3: จับคู่คำสั่งของคุณ (ส่วนที่คุณตั้งใจมาหา)
นี่คือหัวใจสำคัญของการโยกย้าย นี่คือวิธีการแปลคำสั่ง inso เป็น apidog run
| สิ่งที่คุณต้องการทำ | คำสั่ง inso | เทียบเท่า Apidog CLI |
|---|---|---|
| รันชุดทดสอบหน่วย | inso run test "Smoke Suite" --env "Staging" |
apidog run --test-scenario "Smoke Suite" -e staging |
| รันคอลเลกชัน | inso run collection "Checkout Flow" --env "Staging" |
apidog run "Checkout Flow" -e staging |
| รันสคริปต์ที่ระบุชื่อ | inso script ci-smoke --env <env-id> |
apidog run -e <env-id> (เชื่อมต่อกับสคริปต์ CI ของคุณ) |
| Lint สเปค OpenAPI | inso lint spec "My API Design" |
ไม่มี 1:1; Apidog ตรวจสอบความถูกต้องเมื่อนำเข้า |
| ส่งออกสเปคไปยังไฟล์ | inso export spec "My API Design" --output api.yaml |
จัดการโดยการนำเข้า/ส่งออกของ Apidog ไม่ใช่ขั้นตอนรันไทม์ |
ข้อสังเกตบางประการเกี่ยวกับการจับคู่:
- สภาพแวดล้อม
insoใช้--env "ชื่อ"Apidog ใช้-e(--env) ทั้งสองตัวเลือกใช้เพื่อเลือก URL พื้นฐานและตัวแปรของสภาพแวดล้อมที่จะนำไปใช้ สร้างสภาพแวดล้อม Insomnia ของคุณใหม่เป็นสภาพแวดล้อม Apidog ก่อน จากนั้นอ้างอิงตามชื่อหรือ ID - ชุดทดสอบกลายเป็นสถานการณ์ทดสอบ ในขณะที่
inso run testรันชุดทดสอบหน่วยของ Insomnia, Apidog รันสถานการณ์ทดสอบ แนวคิดนี้จับคู่กันได้อย่างชัดเจน: คำสั่งที่จัดเรียงพร้อมกับการยืนยัน คุณจะต้องสร้างชุดนี้ใหม่ใน Apidog เพียงครั้งเดียว จากนั้นก็จะรันทุกครั้งที่ใช้apidog run inso scriptเป็นการอ้อม หากคุณใช้คำสั่งซ้อนอยู่เบื้องหลังสคริปต์ที่มีชื่อ ก็แค่เรียกใช้apidog runโดยตรงในขั้นตอน CI ของคุณ หรือห่อหุ้มไว้ในสคริปต์ npm/make ของคุณเอง
สำหรับการเปรียบเทียบคำสั่งต่อคำสั่งที่ลึกซึ้งยิ่งขึ้น Apidog CLI vs inso (Insomnia CLI) จะครอบคลุมถึงแต่ละแฟล็ก หากคุณเคยใช้ Newman หรือ Postman CLI มาก่อน Apidog CLI vs Newman และ Apidog CLI vs Postman CLI ก็มีครอบคลุมเช่นกัน
ขั้นตอนที่ 4: ย้ายตัวรายงานของคุณ
inso อาศัยเอาต์พุตการทดสอบและการรายงานสไตล์ JUnit สำหรับ CI Apidog ให้ตัวรายงานในรูปแบบ CLI, HTML และ JSON ดังนั้นบิลด์ของคุณสามารถพิมพ์ผลลัพธ์ที่มนุษย์อ่านได้ไปยังคอนโซล และปล่อยอาร์ติแฟกต์ที่เครื่องอ่านได้ในเวลาเดียวกัน:
# รันสถานการณ์และส่งออกสรุป CLI และรายงาน HTML ทั้งคู่
apidog run --test-scenario "Smoke Suite" -e staging -r cli,html
เลือก json เมื่อเครื่องมือดาวน์สตรีมต้องการแยกวิเคราะห์ผลลัพธ์, html เมื่อมนุษย์ตรวจสอบบิลด์ และ cli สำหรับฟีดคอนโซลแบบสด คุณยังสามารถพุชผลลัพธ์ไปยังรายงานการทดสอบบนคลาวด์ของ Apidog ด้วย --upload-report เพื่อให้ทั้งทีมเห็นการรันโดยไม่ต้องขุดคุ้ยบันทึก CI คู่มือรายงานการทดสอบ จะครอบคลุมรูปแบบโดยละเอียด
ขั้นตอนที่ 5: นำการทดสอบแบบขับเคลื่อนด้วยข้อมูลมาใช้
หากชุด Insomnia ของคุณวนลูปข้อมูล Apidog รองรับการทดสอบแบบขับเคลื่อนด้วยข้อมูลโดยกำเนิด ป้อนชุดข้อมูล CSV หรือ JSON ด้วย -d และสถานการณ์จะทำงานหนึ่งครั้งต่อหนึ่งแถว:
apidog run --test-scenario "Login Matrix" -e staging -d ./users.csv -r cli,json
นี่เป็นจุดหนึ่งที่ Apidog มักจะรู้สึกไม่ถูกยึดติดเท่ากับการเชื่อมโยงข้อมูลภายนอกผ่าน inso คู่มือการทดสอบแบบขับเคลื่อนด้วยข้อมูล จะอธิบายรูปแบบชุดข้อมูลและการผูกตัวแปร
ขั้นตอนที่ 6: เชื่อมต่อเข้ากับ CI
ขั้นตอนสุดท้ายคือการสลับคำสั่งในไปป์ไลน์ของคุณ GitHub Actions หรือ GitLab เก่าของคุณอาจดูเหมือนเป็นแบบนี้:
# ก่อนหน้า: inso ใน CI
inso run test "Smoke Suite" --env "CI" --reporter junit
เทียบเท่ากับ Apidog:
# หลังจาก: Apidog CLI ใน CI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json --upload-report
ตรวจสอบสิทธิ์ผู้รันด้วยโทเค็นการเข้าถึงที่จัดเก็บเป็นความลับใน CI เช่นเดียวกับที่คุณจัดการขั้นตอนการรับรองความถูกต้องอื่นๆ คู่มือ CI/CD pipeline และ คู่มือ GitHub Actions มีไฟล์เวิร์กโฟลว์ที่สามารถคัดลอกและวางได้ สำหรับรายละเอียดโทเค็นและการเข้าสู่ระบบ โปรดดู การตรวจสอบสิทธิ์ Apidog CLI
หากคุณยังคงใช้ Spectral สำหรับการลินต์ (แนะนำหากคุณมีกฎที่กำหนดเอง) ตอนนี้ไปป์ไลน์ของคุณมีสองเกณฑ์: Spectral ลินต์สเปค และ Apidog รันการทดสอบ นั่นเป็นสถานะสุดท้ายที่สมเหตุสมผล และแสดงให้เห็นอย่างตรงไปตรงมาว่าเครื่องมือแต่ละชนิดทำอะไรได้ดีที่สุด
การรักษา Spectral ให้อยู่ในระบบ
เพื่อให้ชัดเจนเกี่ยวกับสิ่งหนึ่งที่ไม่สามารถพอร์ตได้: หากการลินต์เป็นส่วนหนึ่งของสัญญาของคุณ อย่าละทิ้งมัน Spectral เป็นโอเพนซอร์สและทำงานได้ดีนอก Insomnia CI แบบไฮบริดโดยทั่วไปจะมีลักษณะดังนี้:
# Lint ด้วย Spectral (เก็บไว้จากการตั้งค่า inso ของคุณ)
npx @stoplight/spectral-cli lint my-api.yaml
# ทดสอบด้วย Apidog CLI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json
คุณไม่สูญเสียอะไรในส่วนของการลินต์ และได้รับแพลตฟอร์มการออกแบบ-จำลอง-ทดสอบ-เอกสารประกอบแบบบูรณาการของ Apidog ในทุกสิ่งทุกอย่าง นั่นคือการแลกเปลี่ยนที่แม่นยำ และเป็นสิ่งที่ดีสำหรับทีมส่วนใหญ่
inso vs Apidog CLI โดยสรุป
| ความสามารถ | inso (Insomnia CLI) | Apidog CLI |
|---|---|---|
| รันคอลเลกชัน / ชุดทดสอบ | ใช่ | ใช่ |
| สภาพแวดล้อม | --env |
-e / --env |
| การลินต์ OpenAPI | ใช่ (Spectral) | ไม่มีคำสั่งสแตนด์อโลน (ตรวจสอบความถูกต้องเมื่อนำเข้า) |
| การทดสอบแบบขับเคลื่อนด้วยข้อมูล | จำกัด | ใช่ (-d, CSV/JSON) |
| รูปแบบรายงาน | CLI, JUnit | CLI, HTML, JSON, อัปโหลดขึ้นคลาวด์ |
| ทรัพยากรในรูปแบบโค้ด | อ่านไดเรกทอรี .insomnia |
เอนด์พอยต์, สกีมา, สาขา, คำขอรวม (merge requests) |
| ส่วนหนึ่งของแพลตฟอร์มรวม | Insomnia + เครื่องมือภายนอก | แพลตฟอร์มเดียว (ออกแบบ, จำลอง, เอกสารประกอบ, ทดสอบ) |
| ต้องมีบัญชีคลาวด์สำหรับแอป | ใช่ (Insomnia 8+) | บัญชี Apidog, รองรับการใช้งานแบบ local |
คำถามที่พบบ่อย
Insomnia OpenAPI spec ของฉันจะนำเข้าสู่ Apidog ได้โดยไม่ต้องแก้ไขหรือไม่? โดยปกติแล้วจะได้ Apidog อ่าน OpenAPI ได้โดยตรงและตรวจสอบความถูกต้องเมื่อนำเข้า หากการตรวจสอบพบปัญหา มักจะเป็นปัญหาโครงสร้างที่แท้จริงในสเปค และการแก้ไขครั้งเดียวจะเป็นประโยชน์ต่อเครื่องมือทุกตัวในขั้นตอนต่อไป
Apidog CLI มีคำสั่ง lint เหมือน inso lint spec หรือไม่? ไม่มี Apidog ตรวจสอบความถูกต้องของสเปคเมื่อนำเข้า แต่ไม่มี linter CLI แบบสแตนด์อโลนหรือคำสั่งสไตล์ไกด์ หากคุณพึ่งพาชุดกฎ Spectral ที่กำหนดเอง ให้เก็บ Spectral ไว้ในไปป์ไลน์ถัดจาก apidog run สำหรับการเปรียบเทียบแบบเคียงข้างกัน โปรดดู Apidog CLI vs Redocly CLI เนื่องจาก Redocly CLI มี linter
ฉันสามารถรัน Apidog CLI ใน CI ได้เหมือนที่ฉันรัน inso หรือไม่? ใช่ สลับคำสั่ง ตรวจสอบสิทธิ์ด้วยโทเค็นการเข้าถึงจากความลับของ CI และเลือกตัวรายงานของคุณ คู่มือ CI/CD มีตัวอย่างเวิร์กโฟลว์แบบเต็ม
จะเกิดอะไรขึ้นกับชุดทดสอบหน่วยของ Insomnia ของฉัน? คุณสร้างมันขึ้นมาใหม่เป็นสถานการณ์ทดสอบ Apidog โครงสร้างจะถูกถ่ายทอดโดยตรง: คำขอที่จัดเรียงพร้อมกับการยืนยัน เป็นการสร้างใหม่เพียงครั้งเดียว หลังจากนั้นจะรันทุกครั้งที่ใช้ apidog run
ฉันกำลังย้ายออกจาก Insomnia เนื่องจากข้อมูลสูญหาย ฉันควรเริ่มต้นจากตรงไหน? กู้คืนข้อมูลของคุณก่อนโดยใช้ คู่มือการกู้คืนและส่งออก จากนั้นทำตามขั้นตอนที่ 2 ด้านบนเพื่อนำเข้าข้อมูลที่ส่งออกที่สะอาดแล้วเข้าสู่ Apidog
สรุป
การย้ายจาก inso ไปยัง Apidog CLI ส่วนใหญ่เป็นงานแปล: ส่งออกสเปคและชุดทดสอบของคุณ นำเข้าสู่ Apidog เขียน inso run test และ inso run collection ใหม่เป็น apidog run เปลี่ยน --env เป็น -e และชี้ตัวรายงานของคุณไปที่เอาต์พุต CLI/HTML/JSON ของ Apidog หากคุณใช้การลินต์ ให้เก็บ Spectral ไว้ เพราะ Apidog ตรวจสอบความถูกต้องเมื่อนำเข้าแต่ไม่สามารถแทนที่ชุดกฎที่กำหนดเองได้
ผลตอบแทนคือแพลตฟอร์มเดียวแทนที่จะเป็นสแต็คที่คุณต้องคอยเชื่อมต่อเข้าด้วยกัน พร้อมที่จะลองหรือยัง? ดาวน์โหลด Apidog และรัน apidog run ครั้งแรกของคุณกับสเปคที่คุณเพิ่งส่งออกไป