ตรวจสอบ API ของคุณตามข้อกำหนดโดยไม่ต้องใช้ Dredd

Dredd แก้ปัญหาที่แท้จริง และแก้ได้อย่างสะอาดหมดจด คุณชี้ไปที่คำอธิบาย API, เอกสาร OpenAPI หรือไฟล์ API Blueprint และไปยังเซิร์ฟเวอร์ที่กำลังทำงานอยู่ มันจะอ่านตัวอย่างทั้งหมดในคำอธิบาย ส่งคำขอที่ตรงกันไปยังแบ็กเอนด์จริง และตรวจสอบว่าการตอบสนองจริงตรงกับที่สเปกสัญญาไว้ หากสเปกของคุณระบุว่า GET /orders/{id} ส่งคืน 200 พร้อมฟิลด์ id และ status Dredd จะยืนยันว่าบริการที่กำลังทำงานอยู่ทำเช่นนั้นจริง สเปกจะไม่ใช่เอกสารที่ค่อยๆ เสื่อมสภาพอีกต่อไป แต่กลายเป็นชุดทดสอบที่แจ้งความล้มเหลวอย่างชัดเจน

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

ปัญหาอยู่ที่การตั้งค่าและการบำรุงรักษา ไม่ใช่แนวคิด Dredd เป็น CLI ของ Node.js ที่ต้องใช้ไฟล์คอนฟิกของตัวเอง ไฟล์ hooks ในภาษาที่คุณเลือกสำหรับกรณีที่ไม่ใช่เรื่องเล็กน้อย และสเปกอาร์ติแฟกต์แยกต่างหากที่คุณดูแลด้วยตนเองควบคู่ไปกับสิ่งอื่นๆ หากคุณต้องการผลลัพธ์แบบเดียวกันกับที่ Dredd ให้คุณ นั่นคือ CI gate ที่จะแจ้งความล้มเหลวเมื่อการใช้งานของคุณไม่ตรงกับสัญญา OpenAPI อีกต่อไป โดยไม่ต้องตั้งค่า toolchain ของ hooks และไม่ต้องเก็บสเปกไว้เป็นไฟล์ที่สามที่ไม่เชื่อมต่อกัน Apidog ถูกสร้างขึ้นสำหรับเวิร์กโฟลว์นั้น มันเก็บสเปก ชุดทดสอบ และการตรวจสอบไว้ในโปรเจกต์เดียว และรันทั้งหมดแบบ headlessly จาก npm CLI คู่มือนี้จะบอกเล่าอย่างยุติธรรมว่า Dredd ทำอะไรได้ดี และชัดเจนว่าเส้นทางแบบรวมศูนย์มีข้อดีอย่างไร

สิ่งที่ Dredd ทำได้ดี

มาพูดถึงข้อดีของ Dredd ก่อน เพราะมันสร้างชื่อเสียงให้กับตัวเอง

มันทดสอบการใช้งานจริง ไม่ใช่การจำลอง นี่คือหัวใจสำคัญของมัน มีเครื่องมือมากมายที่ตรวจสอบว่าไฟล์ OpenAPI ของคุณมีโครงสร้างที่ดี หรือเซิร์ฟเวอร์จำลองทำงานได้ตามปกติ Dredd ทำสิ่งที่ยากกว่านั้น: มันจะเรียกแบ็กเอนด์ที่กำลังทำงานจริง และตรวจสอบข้อมูลจริงที่ส่งกลับมาเทียบกับตัวอย่างที่ระบุไว้ การรัน Dredd ที่ผ่านหมายความว่าบริการที่คุณปรับใช้และสเปกของคุณตรงกันในตอนนี้ ไม่ใช่แค่ในทางทฤษฎี

รองรับทั้ง API Blueprint และ OpenAPI Dredd พัฒนาควบคู่ไปกับ API Blueprint ซึ่งเป็นรูปแบบคำอธิบายที่ใช้ Markdown และภายหลังได้เพิ่มการรองรับ OpenAPI 2 และ 3 หากคุณมีไฟล์ Blueprint รุ่นเก่าหรือเอกสาร Swagger Dredd สามารถอ่านได้โดยไม่ต้องแปลง

Hooks ที่ไม่ขึ้นกับภาษา เมื่อการวนลูปส่งคำขอและเปรียบเทียบค่าเริ่มต้นไม่เพียงพอ คุณต้องใช้โทเค็นการยืนยันตัวตน คุณต้องเตรียมข้อมูลในฐานข้อมูลก่อนการทดสอบ คุณต้องข้ามธุรกรรม Dredd ช่วยให้คุณสามารถเขียน hooks ได้ ตัวจัดการ hook จะทำงานใน Node โดยค่าเริ่มต้น แต่ Dredd รองรับโปรโตคอลสำหรับ hooks ใน Python, Ruby, Go, PHP, Rust และอื่นๆ ทีมของคุณสามารถเขียนโค้ดสำหรับตั้งค่าในภาษาที่คุ้นเคยอยู่แล้ว

เป็นโอเพ่นซอร์สและรองรับ CI Dredd ติดตั้งด้วย npm install -g dredd รันด้วยคำสั่งเดียว และจะคืนค่าที่ไม่ใช่ศูนย์เมื่อการตรวจสอบล้มเหลว ดังนั้นระบบ CI ใดๆ ก็สามารถใช้เป็นตัวควบคุมการ build ได้ ไม่มีบัญชี SaaS ไม่มีราคาต่อที่นั่ง ไม่มีอะไรต้องลงทะเบียน สำหรับทีมที่ต้องการการตรวจสอบสัญญาแบบ self-hosted และสามารถเขียนสคริปต์ได้ สิ่งนี้มีความสำคัญ

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

จุดที่เกิดปัญหา

โมเดลของ Dredd มาพร้อมกับสามค่าใช้จ่าย และความเสียหายขึ้นอยู่กับการตั้งค่าของคุณ

สเปกเป็นอาร์ติแฟกต์ที่สามที่คุณดูแลด้วยตนเอง Dredd ตรวจสอบการใช้งานเทียบกับไฟล์คำอธิบาย ซึ่งถูกต้องแม่นยำ แต่คำอธิบายนั้นมักจะแยกจากที่ที่คุณออกแบบและทดสอบ API คุณแก้ไข openapi.yaml ด้วยตนเอง คุณเก็บสถานการณ์จำลองการทดสอบไว้ที่อื่น และคุณเก็บบริการที่กำลังทำงานไว้ที่อื่นอีกครั้ง Dredd ตรวจสอบสองในสามสิ่งนี้เทียบกับกัน การรักษาสเปกให้ถูกต้องแม่นยำยังคงเป็นงานที่ต้องทำด้วยตนเอง และสเปกที่เบี่ยงเบนจากความเป็นจริงอย่างเงียบๆ จะทำให้การรัน Dredd ผ่านแต่ผิดพลาด

Hooks คือโค้ดที่คุณเขียนและดูแลรักษา ทันทีที่ API ของคุณต้องการการยืนยันตัวตน การจัดลำดับ หรือข้อมูลทดสอบ การวนลูปที่ขับเคลื่อนด้วยตัวอย่างก็จะไม่เพียงพอ คุณเขียน hooks.js (หรือเทียบเท่าใน Python หรือ Ruby) กำหนดค่าผ่าน dredd.yml และตอนนี้คุณก็เป็นเจ้าของโค้ดเบสที่สองซึ่งมีหน้าที่เดียวคือทำให้โค้ดเบสแรกสามารถทดสอบได้ สำหรับ API แบบอ่านอย่างเดียวที่เรียบง่าย Dredd แทบจะไม่มีการกำหนดค่าเลย สำหรับ API จริงที่มีการล็อกอินและเอนด์พอยต์ที่มีสถานะ ไฟล์ hooks จะใหญ่ขึ้น และมันคือโค้ดเชื่อมต่อในอีกชื่อหนึ่ง

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

เส้นทางแบบรวมศูนย์: สเปกและชุดทดสอบในโปรเจกต์เดียว

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

คุณออกแบบหรือนำเข้า API เพียงครั้งเดียว Apidog สามารถอ่าน OpenAPI 2 และ 3, นำเข้าเอกสาร Swagger และดึง Postman collections ได้ในคลิกเดียว เอนด์พอยต์, สคีมาคำขอ, สคีมาการตอบกลับ และการตอบกลับตัวอย่าง ทั้งหมดอยู่ในโปรเจกต์เดียวกัน หากคุณคิดแบบ spec-first อยู่แล้ว นี่คือแนวทางปฏิบัติเดียวกับที่ Dredd ส่งเสริม เพียงแต่สเปกไม่ได้เป็นไฟล์ที่แยกต่างหาก เวอร์ชันที่ลึกซึ้งกว่าของเวิร์กโฟลว์นั้นอยู่ใน การพัฒนา API แบบ spec-first และหากคุณต้องการตรวจสอบเอกสารสเปกเองก่อนที่จะรันการทดสอบใดๆ การตรวจสอบสเปก OpenAPI ครอบคลุมขั้นตอนนี้

คุณสร้างการตรวจสอบเทียบกับสคีมาจริงเหล่านั้น เมื่อสถานการณ์ทดสอบเรียกใช้ GET /orders/{id} คุณจะยืนยันการตอบกลับเทียบกับสคีมาที่ Apidog มีอยู่สำหรับเอนด์พอยต์นั้น ไม่ใช่เทียบกับตัวอย่างที่คัดลอกด้วยมือ นั่นคือการตรวจสอบสเปกเทียบกับการใช้งานที่ Dredd ดำเนินการ ด้วยความแตกต่างอย่างหนึ่ง: สเปกที่ถูกตรวจสอบคือวัตถุเดียวกันกับที่คุณออกแบบ API มา ดังนั้นจึงไม่สามารถหลุดจากการทำงานร่วมกับชุดทดสอบของคุณได้อย่างเงียบๆ นี่คือการทดสอบสัญญาโดยไม่มีอาร์ติแฟกต์ที่สาม และหากคุณต้องการภาพรวมที่กว้างขึ้นของแนวทางปฏิบัตินั้น การทดสอบสัญญา API และ การทดสอบสัญญาแบบสองทาง ทั้งคู่จะลงลึกยิ่งขึ้น

การตั้งค่าที่ Dredd จัดการด้วยไฟล์ hooks, โทเค็นการยืนยันตัวตน, การจัดลำดับ, การเตรียมข้อมูล คุณสามารถจัดการได้ด้วยสคริปต์ pre-request และ post-request ใน JavaScript ซึ่งนักพัฒนาเว็บส่วนใหญ่เขียนอยู่แล้ว ไม่ต้องมีโค้ดเบส hooks แยกต่างหากที่เชื่อมต่อผ่านไฟล์คอนฟิก ตรรกะจะอยู่ถัดจากการทดสอบที่รองรับ

การติดตั้งและรัน Apidog CLI

ไบนารีถูกเผยแพร่ไปยัง npm ในชื่อ apidog-cli หากคุณมี Node.js คุณก็มีทุกสิ่งที่ต้องการแล้ว:

npm install -g apidog-cli

ไบนารีคือ apidog ดังนั้นการรันทุกครั้งจะเริ่มต้นด้วย apidog run ในการรันสถานการณ์ทดสอบ คุณต้องส่ง access token, ID สถานการณ์ และ ID สภาพแวดล้อม:

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

คุณไม่จำเป็นต้องพิมพ์ ID เหล่านั้นด้วยตนเอง เปิดสถานการณ์ทดสอบใน Apidog ไปที่แท็บ CI/CD เลือกตัวเลือก command-line และสร้าง access token Apidog จะสร้างคำสั่ง apidog run เต็มรูปแบบให้คุณ โดยมี ID สถานการณ์และสภาพแวดล้อมที่กรอกไว้แล้ว คัดลอกไปใช้ครั้งเดียวและปรับพารามิเตอร์ของโทเค็นจากตรงนั้น ปฏิบัติกับ access token เหมือนรหัสผ่าน: จัดเก็บเป็นความลับในระบบ CI ของคุณและอ้างอิงถึงเป็น `$APIDOG_ACCESS_TOKEN` เหมือนกับตัวอย่างทุกตัวอย่างในที่นี้

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

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports

แฟล็ก `-r` ใช้สำหรับเลือกผู้รายงาน Apidog รองรับ cli สำหรับเอาต์พุตที่อ่านง่ายในเทอร์มินัล, html สำหรับรายงานแบบครบวงจรที่คุณเก็บเป็น build artifact, junit สำหรับ XML ที่แดชบอร์ด CI เกือบทุกตัวสามารถแยกวิเคราะห์เป็นแผนผังผ่าน/ไม่ผ่านได้ และ json สำหรับผลลัพธ์โครงสร้างดิบ หากคุณต้องการทราบรายละเอียดเพิ่มเติมเกี่ยวกับ runner ให้รัน apidog run --help เพื่อดูรายการแฟล็กทั้งหมด

เปรียบเทียบ

อ่านตารางนั้นอย่างตรงไปตรงมา หากคุณต้องการเครื่องมือแบบ self-hosted, โอเพ่นซอร์ส, ไม่ต้องมีบัญชี และทีมของคุณสะดวกกับการดูแลไฟล์ hooks โมเดลของ Dredd ก็เหมาะสมอย่างยิ่ง และการเปลี่ยนไปใช้สิ่งอื่นโดยไม่มีเหตุผลจะไม่ได้ประโยชน์อะไร กรณีของเส้นทางแบบรวมศูนย์นั้นเฉพาะเจาะจง: คุณเบื่อที่สเปกเป็นไฟล์ที่สามที่คลาดเคลื่อน คุณไม่ต้องการเป็นเจ้าของโค้ดเบส hooks หรือคุณต้องการให้โปรเจกต์เดียวกันจัดการการออกแบบ การทดสอบ และการตรวจสอบสัญญาพร้อมกัน

การเชื่อมต่อเข้ากับ CI

Apidog CLI จะคืนค่าศูนย์เมื่อผ่านและค่าที่ไม่ใช่ศูนย์เมื่อล้มเหลว ดังนั้นระบบ CI ใดๆ ก็สามารถใช้เป็นตัวควบคุมการ build ได้ เช่นเดียวกับ Dredd งาน GitHub Actions ขั้นต่ำต้องการ Node และขั้นตอนการรันหนึ่งขั้นตอน:

name: api-contract-check
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

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

หากเหตุผลที่คุณเลือกใช้ Dredd คือการรักษาให้สเปกและบริการซื่อสัตย์ต่อกัน ตรรกะเดียวกันนี้ก็ปรากฏในเครื่องมืออื่นๆ ทีมงานประสบปัญหาสเปก Swagger และ Postman ที่คลาดเคลื่อน ซึ่ง การทดสอบที่ขับเคลื่อนด้วย OpenAPI กับความคลาดเคลื่อนของ Swagger และ Postman ครอบคลุม และร้านค้า Java ก็ประสบปัญหากับ Rest Assured ซึ่งเรื่องราวของ ทางเลือกอื่น ก็คล้ายกัน: เครื่องมือที่แข็งแกร่งซึ่งโมเดลเพิ่มชั้นที่คุณอาจไม่ต้องการ คุณยังสามารถขับเคลื่อน Apidog จาก editor ของคุณด้วย ส่วนขยาย VS Code หากคุณไม่ต้องการออกจาก IDE ของคุณ

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

Apidog เป็นตัวแทนที่สามารถนำมาใช้แทน Dredd ได้ทันทีหรือไม่? ไม่ใช่ และไม่ได้แกล้งทำเป็นว่าใช่ ไม่มีตัวแปลงที่อ่าน dredd.yml และ hooks.js ของคุณแล้วสร้างสถานการณ์ Apidog ได้ คุณต้องนำเข้าสเปก OpenAPI ของคุณแล้วสร้างการตรวจสอบใหม่ใน visual editor ข้อดีคือคุณหยุดดูแลไฟล์ hooks และสเปกที่แยกจากกัน; ค่าใช้จ่ายคือการสร้างใหม่เพียงครั้งเดียว หากคุณมีชุดทดสอบ Dredd ขนาดใหญ่และสมบูรณ์ที่ใช้งานได้ การสร้างใหม่นั้นเป็นการตัดสินใจที่สำคัญ ไม่ใช่เรื่องง่ายๆ

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

ฉันยังคงจัดการการยืนยันตัวตนและการตั้งค่าการทดสอบได้เหมือนกับที่ Dredd hooks ทำได้หรือไม่? ใช่ Apidog รองรับสคริปต์ pre-request และ post-request ใน JavaScript ดังนั้นคุณจึงสามารถดึงโทเค็นการยืนยันตัวตน, เตรียมข้อมูล, แปลงเพย์โหลด หรือสร้างการยืนยันแบบไดนามิกในโค้ดได้ ตรรกะจะอยู่ในสถานการณ์ที่รองรับ แทนที่จะอยู่ในไฟล์ hooks แยกต่างหากที่เชื่อมต่อผ่านการกำหนดค่า

Dredd ทำอะไรที่ Apidog ทำไม่ได้บ้าง? มีบางอย่าง Dredd เป็นแบบ self-hosted และโอเพ่นซอร์สอย่างสมบูรณ์โดยไม่ต้องมีบัญชี และสามารถอ่าน API Blueprint ซึ่งเป็นรูปแบบคำอธิบาย Markdown รุ่นเก่าได้โดยตรง หากเครื่องมือที่ไม่ต้องมีบัญชี, ทำงานแบบ local อย่างสมบูรณ์ หรือไฟล์ Blueprint รุ่นเก่าเป็นหัวใจสำคัญในการตั้งค่าของคุณ ให้พิจารณาอย่างรอบคอบก่อนที่จะเปลี่ยน

Apidog อ่านรูปแบบใดได้บ้าง? OpenAPI 2 และ 3, เอกสาร Swagger และ Postman collections ซึ่งทั้งหมดสามารถนำเข้าสู่โปรเจกต์เดียวได้ หากคุณต้องการทำความเข้าใจความแตกต่างของรูปแบบก่อน Swagger เทียบกับ OpenAPI และ ภาพรวมของสเปก OpenAPI ทั้งสองจะอธิบายรายละเอียดไว้

สรุป

Dredd มีแนวคิดหลักที่ถูกต้อง: คำอธิบาย API ของคุณควรเป็นสิ่งที่คุณใช้ทดสอบบริการที่กำลังทำงานอยู่ ไม่ใช่เอกสารที่คลาดเคลื่อน หากคุณต้องการ CLI แบบ self-hosted, โอเพ่นซอร์ส และคุณยินดีที่จะดูแลไฟล์สเปกและไฟล์ hooks Dredd เป็นตัวเลือกที่ดีและคุณควรใช้ต่อไป

เส้นทางแบบรวมศูนย์เหมาะสำหรับกรณีที่คุณต้องการกำจัดภาระการดูแลรักษานั้น Apidog เก็บสเปก ชุดทดสอบ และการตรวจสอบไว้ในโปรเจกต์เดียว ดังนั้นสัญญาที่คุณตรวจสอบจึงเป็นอันเดียวกับที่คุณออกแบบมา และมันรันทุกอย่างจาก apidog run โดยไม่ต้องมีโค้ดเบส hooks ที่ต้องเป็นเจ้าของ ดาวน์โหลด Apidog และนำเข้าไฟล์ OpenAPI ที่มีอยู่ของคุณ เพื่อดูการตรวจสอบสเปกเทียบกับการใช้งานจริงที่รันได้จากคำสั่งเดียว