การพูลรีเควสต์แก้ไข openapi.yaml การตรวจสอบ CI เป็นสีเขียว สเปคถูกต้อง ลินต์สะอาด และมีผู้ตรวจสอบสองคนอนุมัติ สามวันต่อมา ไคลเอนต์บนมือถือเริ่มเกิดข้อผิดพลาด null-pointer crashes เนื่องจากฟิลด์การตอบกลับที่เคยมีอยู่หายไป ไม่มีใครลบมันโดยเจตนา มีคนเปลี่ยนชื่อคุณสมบัติระหว่างการปรับโครงสร้างโค้ด (refactor) และไม่มีอะไรในการรีวิวตรวจจับได้
นี่คือช่องว่างที่ตัวตรวจสอบธรรมดาไม่เคยเห็น สเปคอาจจะจัดรูปแบบมาอย่างดีเยี่ยม แต่ก็ยังสามารถทำให้ทุกผู้ใช้งานที่ต้องพึ่งพามันเสียหายได้ วิธีเดียวที่จะรู้ได้คือการเปรียบเทียบสเปคใหม่กับเวอร์ชันที่มันจะเข้ามาแทนที่ ทีละการเปลี่ยนแปลง และถามคำถามเดียวว่า: สิ่งนี้จะทำให้ไคลเอนต์ที่เคยใช้งานได้เมื่อวานเสียหายหรือไม่? การเปรียบเทียบนั้นคือ OpenAPI diff และการรันมันในฐานะ merge gate เป็นหนึ่งในการตรวจสอบที่ให้ผลตอบแทนสูงสุดที่คุณสามารถเพิ่มเข้าไปใน API repo ของคุณได้
สิ่งที่ OpenAPI diff เปรียบเทียบจริงๆ
OpenAPI diff จะนำข้อมูลจำเพาะสองชุด คือ base และ head มาเปรียบเทียบ และรายงานสิ่งที่เปลี่ยนแปลงไประหว่างกัน โดยปกติ base คือสเปคที่อยู่ใน target branch ของคุณ (เวอร์ชันที่ใช้งานจริง) ส่วน head คือสเปคที่ pull request ของคุณเสนอ เครื่องมือ diff ที่ดีไม่ได้เพียงแค่แสดงความแตกต่างในรูปแบบข้อความเหมือนที่ git diff ทำ แต่มันเข้าใจโครงสร้างของ OpenAPI จึงสามารถแยกแยะความแตกต่างระหว่างการแก้ไขเพื่อความสวยงามกับการเปลี่ยนแปลงที่ทำลายสัญญา (contract-breaking) ได้
นี่คือความแตกต่างที่สำคัญ การเปลี่ยนแปลงบางอย่างเป็นการเพิ่มเข้ามาและปลอดภัย:
- การเพิ่มพารามิเตอร์คำขอเสริมใหม่
- การเพิ่มฟิลด์การตอบกลับใหม่
- การเพิ่มเอนด์พอยต์ใหม่ทั้งหมด
- การเพิ่มค่า enum ใหม่ให้กับเนื้อหาคำขอ
ไคลเอนต์ปัจจุบันยังคงทำงานได้ตามปกติจากการเปลี่ยนแปลงทั้งหมดเหล่านี้ พวกเขายังคงส่งข้อมูลที่เคยส่ง และอ่านข้อมูลที่เคยอ่าน การเปลี่ยนแปลงอื่นๆ ไม่สามารถเข้ากันได้แบบย้อนหลัง (backward-incompatible) และสิ่งเหล่านี้คือสิ่งที่สร้างปัญหา:
- การลบฟิลด์การตอบกลับที่ไคลเอนต์อ่าน
- การเปลี่ยนชื่อคุณสมบัติ (ซึ่งเทียบเท่ากับการลบแล้วเพิ่มใหม่ในมุมมองของไคลเอนต์)
- การทำให้พารามิเตอร์ที่เคยเป็นทางเลือกกลายเป็นบังคับ
- การจำกัดประเภทข้อมูลให้แคบลง เช่น จาก
stringเป็นinteger - การลบค่า enum ที่ไคลเอนต์อาจส่ง
- การลบเอนด์พอยต์หรือเมธอด HTTP
หน้าที่ของเครื่องมือ OpenAPI diff คือการสแกนทุกเส้นทาง (path), พารามิเตอร์ (parameter), สคีมา (schema) และการตอบกลับ (response) ทั่วทั้งสองเอกสาร และจัดเรียงการเปลี่ยนแปลงแต่ละอย่างลงในกลุ่มเหล่านั้น การจัดหมวดหมู่นั้นคือหัวใจสำคัญ การเปรียบเทียบแบบบรรทัดดิบอาจซ่อนฟิลด์ required ที่ถูกลบไว้ใต้การจัดรูปแบบใหม่ห้าสิบบรรทัด การเปรียบเทียบแบบโครงสร้างจะเปิดเผยสิ่งนั้นในฐานะ breaking change และบอกคุณว่ามันอยู่ที่เส้นทางใด
หากคุณต้องการแบบจำลองทางความคิดเบื้องหลังว่าทำไมการเปลี่ยนแปลงบางอย่างจึงทำให้ระบบเสียหายในขณะที่บางอย่างไม่เสียหาย คู่มือเรื่อง วิธีการกำหนดเวอร์ชันและเลิกใช้งาน API ในขนาดใหญ่ ได้ครอบคลุมกฎการเข้ากันได้ไว้อย่างละเอียด เครื่องมือ diff เป็นวิธีที่คุณบังคับใช้กฎเหล่านั้นโดยอัตโนมัติ แทนที่จะหวังว่าผู้ตรวจสอบจะจดจำได้
oasdiff: เครื่องมือโอเพนซอร์สที่ทรงประสิทธิภาพ
oasdiff เป็นเครื่องมือโอเพนซอร์สที่ทีมส่วนใหญ่มักเลือกใช้ เป็นไฟล์ไบนารี Go ไฟล์เดียว รวดเร็ว และสร้างขึ้นโดยเฉพาะเพื่อตอบคำถามเกี่ยวกับ breaking change มันอ่านเอกสาร OpenAPI 3.0 และ 3.1 และมีซับคอมมานด์ให้เลือกใช้ตามสิ่งที่คุณต้องการจากการเปรียบเทียบ
สามคำสั่งที่คุณจะใช้บ่อยที่สุด:
diffรายงานความแตกต่างทั้งหมดระหว่างสองสเปคbreakingรายงานเฉพาะการเปลี่ยนแปลงที่ไม่สามารถเข้ากันได้แบบย้อนหลัง (backward-incompatible)changelogสร้างรายการการเปลี่ยนแปลงที่สำคัญทั้งหมดที่มนุษย์อ่านเข้าใจได้ ไม่ว่าจะเป็นการเปลี่ยนแปลงที่เสียหายหรือไม่
สำหรับ merge gate, breaking คือสิ่งที่สำคัญ ชี้มันไปยัง base spec และ head spec ของคุณ:
oasdiff breaking base-openapi.yaml head-openapi.yaml --fail-on ERR
base-openapi.yaml คือสเปคจาก target branch และ head-openapi.yaml คือสเปคใน pull request ซับคอมมานด์ breaking จะพิมพ์เฉพาะการเปลี่ยนแปลงที่ไม่เข้ากันเท่านั้น แฟล็ก --fail-on ERR คือสิ่งที่เปลี่ยนสิ่งนี้ให้เป็นเกต: มันจะทำให้คำสั่งออกด้วยสถานะที่ไม่ใช่ศูนย์เมื่อพบการเปลี่ยนแปลงที่จัดอยู่ในระดับ ERR การออกด้วยค่าที่ไม่ใช่ศูนย์คือสัญญาณสากลที่ CI อ่านว่าล้มเหลว
โมเดลความรุนแรงนั้นเป็นสิ่งที่มีค่าควรแก่การทำความเข้าใจ oasdiff จัดเรียง breaking change ออกเป็นระดับต่างๆ และ ERR เป็นระดับที่รุนแรงที่สุด ซึ่งเป็นการเปลี่ยนแปลงที่จะทำให้ไคลเอนต์เสียหาย WARN ครอบคลุมการเปลี่ยนแปลงที่อาจทำให้ไคลเอนต์บางส่วนเสียหายได้ขึ้นอยู่กับวิธีการเขียน และ INFO เป็นเพียงข้อมูล คุณเป็นผู้ตัดสินใจว่าจะกำหนดเส้นแบ่งไว้ที่ใด --fail-on ERR จะบล็อกเฉพาะการเปลี่ยนแปลงที่แน่นอนว่าจะทำให้เสียหายเท่านั้น --fail-on WARN เข้มงวดกว่าและครอบคลุมถึงการเปลี่ยนแปลงที่อาจจะเสียหายด้วย
เมื่อคุณต้องการสรุปผลที่อ่านง่ายสำหรับ changelog หรือคอมเมนต์ใน PR แทนที่จะเป็นการผ่าน/ไม่ผ่าน ซับคอมมานด์ changelog จะให้ผลลัพธ์ที่เป็นมิตรมากกว่า:
oasdiff changelog base-openapi.yaml head-openapi.yaml
oasdiff มีคุณสมบัติที่มีประโยชน์จริงๆ ไม่กี่อย่าง มันทำการจับคู่เอนด์พอยต์ที่ยังคงทำงานได้แม้มีการเปลี่ยนชื่อพารามิเตอร์ในเส้นทาง ดังนั้นจึงไม่นับว่า {userId} กลายเป็น {id} เป็นการลบแล้วเพิ่มใหม่หากเส้นทางส่วนอื่นเหมือนกัน มันสามารถรวมสคีมา allOf ก่อนการเปรียบเทียบเพื่อไม่ให้การสืบทอดสร้างความสับสน และมันสามารถส่งออกได้มากกว่าแค่ข้อความธรรมดา: HTML, JSON, YAML และ Markdown ล้วนมีให้ใช้งานผ่านแฟล็กเอาต์พุต ซึ่งทำให้ง่ายต่อการป้อนผลลัพธ์ไปยัง CI annotation หรือ changelog ที่สร้างขึ้น สำหรับเครื่องมือที่คุณสามารถใส่ลงในไปป์ไลน์ได้ในห้านาทีและเชื่อถือได้ว่าจะระมัดระวังในการระบุว่าอะไรคือ breaking change มันยากที่จะหาเครื่องมืออื่นมาเปรียบเทียบ
openapi-diff: ทางเลือกสำหรับ JVM
หากระบบของคุณใช้ JVM อยู่แล้ว OpenAPITools/openapi-diff เป็นตัวเลือกที่สองที่แข็งแกร่งและคุ้มค่าที่จะรู้จัก เป็นเครื่องมือที่ใช้ Java (Java 8 ขึ้นไป) ที่เปรียบเทียบสเปค OpenAPI 3.x สองตัวและแสดงความแตกต่างในรูปแบบ HTML, Markdown, AsciiDoc, JSON หรือข้อความคอนโซล คุณสามารถรันมันได้จากไฟล์ jar ที่สร้างขึ้น, ผ่าน Maven, ผ่าน Homebrew หรือเป็นอิมเมจ Docker ดังนั้นจึงเข้ากันได้กับการตั้งค่าการสร้างหลากหลายรูปแบบโดยไม่มีปัญหามากนัก
การเปรียบเทียบของมันเจาะลึกถึงพารามิเตอร์, การตอบกลับ, เอนด์พอยต์ และเมธอด HTTP และมันก็สร้างเส้นแบ่งที่ทุกคนสนใจเหมือนกัน: การเปลี่ยนแปลงที่ยังคงรักษาความเข้ากันได้แบบย้อนหลังกับการเปลี่ยนแปลงที่ทำลายมัน CLI ตรงไปตรงมา:
openapi-diff old-openapi.yaml new-openapi.yaml --fail-on-incompatible
แฟล็ก --fail-on-incompatible จะออกด้วยค่าที่ไม่ใช่ศูนย์เฉพาะเมื่อมีการเปลี่ยนแปลงที่ทำลายความเข้ากันได้แบบย้อนหลัง ซึ่งเป็นพฤติกรรมของเกตที่คุณต้องการพอดี มีแฟล็ก --fail-on-changed ที่เข้มงวดกว่า หากคุณต้องการให้เกิดข้อผิดพลาดในการเปลี่ยนแปลงใดๆ ก็ตาม และโหมด --state ที่จะพิมพ์เพียง no_changes, compatible หรือ incompatible เมื่อคุณต้องการคำตอบสั้นๆ เพื่อใช้ในการเขียนสคริปต์
จุดเด่นของมันคือผลลัพธ์ที่แสดงผล รายงานในรูปแบบ HTML และ Markdown นั้นสะอาดและละเอียด ทำให้ openapi-diff เป็นตัวเลือกที่แข็งแกร่งเมื่อคุณต้องการ artifact ของ diff ที่มนุษย์สามารถอ่านได้จริง ไม่ใช่แค่รหัสออกของ CI ข้อเสียคือการพึ่งพา JVM และการเริ่มต้นที่หนักกว่าไฟล์ไบนารี Go หากทีมของคุณใช้ Java อยู่แล้ว ต้นทุนนั้นเป็นศูนย์และเครื่องมือนี้ก็เข้ากันได้ทันที หากคุณไม่ได้ใช้ Java, oasdiff เป็นทางเลือกที่เบากว่า ทั้งสองตอบคำถาม breaking-change ได้ดี; เลือกอันที่ตรงกับสภาพแวดล้อมรันไทม์ที่คุณดูแลอยู่แล้ว
การเชื่อมต่อ diff เข้ากับ CI ในฐานะ merge gate
การทำ diff ด้วยมือจะไม่พบอะไรเลย เพราะเมื่อไหร่ที่คุณลืมรันมัน นั่นคือเวลาที่การเปลี่ยนแปลงที่ทำให้เสียหายถูกปล่อยออกไป เกตจะต้องอยู่ในไปป์ไลน์และทำงานในทุก pull request ที่เกี่ยวข้องกับสเปค
จุดเล็กๆ ที่ซับซ้อนใน CI คือคุณต้องมีทั้งสองเวอร์ชันของสเปคพร้อมกัน: base จาก target branch และ head จาก PR การเช็คเอาท์ PR ให้คุณได้ head คุณดึง base ออกมาจาก git history โดยตรงโดยไม่ต้องเช็คเอาท์อีกครั้ง:
name: openapi-diff
on:
pull_request:
paths:
- "openapi.yaml"
jobs:
breaking-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Get base spec
run: git show origin/${{ github.base_ref }}:openapi.yaml > base-openapi.yaml
- name: Install oasdiff
run: |
curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh
- name: Diff for breaking changes
run: oasdiff breaking base-openapi.yaml openapi.yaml --fail-on ERR
มีรายละเอียดบางอย่างที่สำคัญในที่นี้ fetch-depth: 0 ดึงประวัติทั้งหมดเพื่อให้ git show สามารถเข้าถึง base branch ได้ บรรทัด git show origin/<base>:openapi.yaml จะอ่านสเปคที่อยู่บน target branch และเขียนลงไฟล์ โดยไม่จำเป็นต้องโคลนเพิ่มเติม ตัวกรอง paths หมายความว่างานนี้จะรันเฉพาะเมื่อสเปคมีการเปลี่ยนแปลงจริงๆ ดังนั้น PR ที่ไม่เกี่ยวข้องจึงไม่ต้องเสียเวลาไปกับมัน และขั้นตอนสุดท้ายคือเกต: หาก oasdiff breaking พบการเปลี่ยนแปลงระดับ ERR มันจะออกด้วยค่าที่ไม่ใช่ศูนย์ งานจะขึ้นเป็นสีแดง และ PR จะแสดงการตรวจสอบที่ไม่ผ่านก่อนที่ใครจะคลิกผสาน
ผู้เขียนจะเห็นอย่างชัดเจนว่าการเปลี่ยนแปลงใดที่ทำให้ความเข้ากันได้เสียหาย บนเส้นทางใด ในขณะที่โค้ดยังอยู่ระหว่างการตรวจสอบ นั่นคือคุณค่าทั้งหมด ความเสียหายจะถูกจับได้ในช่วงเวลาที่ประหยัดที่สุดเท่าที่จะเป็นไปได้ แทนที่จะเป็นในรายงานข้อผิดพลาดของลูกค้า
แน่นอนว่า ไม่ใช่ทุกการเปลี่ยนแปลงที่ทำให้เสียหายจะเป็นความผิดพลาด บางครั้งคุณกำลังเผยแพร่เวอร์ชันหลักที่ตั้งใจไว้ และการเปลี่ยนแปลงที่เสียหายนั้นก็เป็นไปโดยเจตนา รูปแบบที่สะอาดคือการตั้งเกตเป็นค่าเริ่มต้น และกำหนดให้มีการยกเว้นอย่างชัดเจนสำหรับกรณีพิเศษ: การติดป้ายกำกับใน PR, การเพิ่มเวอร์ชันใน info.version หรือเวิร์กโฟลว์ที่อนุมัติแยกต่างหาก ด้วยวิธีนี้ การเปลี่ยนแปลงที่เสียหายจึงเป็นสิ่งที่ตัดสินใจโดยเจตนาเสมอ ไม่ใช่ความผิดพลาดที่เล็ดลอดไปได้ คู่มือกลยุทธ์การกำหนดเวอร์ชัน API จะอธิบายว่าเมื่อใดที่การเปลี่ยนแปลงที่เสียหายสมควรได้รับเวอร์ชันหลักใหม่ กับเมื่อใดที่ควรหลีกเลี่ยง
ช่องว่างที่ diff ไม่สามารถปิดได้
นี่คือข้อจำกัดของทุกเครื่องมือที่กล่าวมาข้างต้น และเป็นข้อจำกัดที่สำคัญ การทำ diff จะเปรียบเทียบไฟล์สองไฟล์ มันจะบอกคุณว่าเอกสารใหม่เข้ากันได้แบบย้อนหลังกับเอกสารเก่า แต่มันไม่ได้บอกว่าบริการที่กำลังทำงานอยู่ของคุณตรงกับเอกสารใดเอกสารหนึ่งหรือไม่
นั่นคือความล้มเหลวที่แตกต่างกัน และเป็นสิ่งที่สร้างปัญหามากที่สุดในการใช้งานจริง (production) สเปคระบุว่ามีฟิลด์ created_at แต่การใช้งานจริงได้หยุดส่งคืนฟิลด์นั้นไปอย่างเงียบๆ ตั้งแต่สามสปรินต์ที่แล้ว สเปคระบุว่าเอนด์พอยต์จะคืนค่า 200 แต่บริการจริงกลับคืนค่า 500 ภายใต้เงื่อนไขที่ไม่มีใครทดสอบ diff สะอาดเพราะสเปคทั้งสองเวอร์ชันเห็นด้วยกัน สัญญาและโค้ดไม่ตรงกัน diff แบบคงที่ไม่มีทางรู้ได้ เพราะมันไม่เคยสื่อสารกับ API
การปิดช่องว่างนั้นหมายถึงการทดสอบ API ที่ใช้งานจริงเทียบกับสัญญา ไม่ใช่แค่การทำ diff สัญญาด้วยตัวมันเอง คุณสร้างการทดสอบจากสเปค รันการทดสอบเหล่านั้นกับบริการที่กำลังทำงานอยู่ และยืนยันว่าการตอบกลับจริงตรงกับรูปแบบที่ระบุไว้ในเอกสาร นั่นคือ การทดสอบสัญญา (contract testing) และเป็นชั้นที่ตรวจจับความคลาดเคลื่อนระหว่างสิ่งที่คุณเขียนไว้กับสิ่งที่คุณเผยแพร่จริง
การปิดช่องว่างด้วย Apidog และ Apidog CLI
Apidog ถูกสร้างมาเพื่อลูปนี้ ซึ่งทำให้มันเป็นเพื่อนร่วมทางที่ดีสำหรับขั้นตอน diff มากกว่าที่จะมาแทนที่ คุณนำเข้าหรือซิงค์ OpenAPI spec ของคุณเข้าไปในโปรเจกต์ Apidog และ Apidog สามารถ สร้างสถานการณ์การทดสอบได้โดยตรงจากสเปค โดยมีการยืนยันที่ได้มาจากสคีมา การทดสอบจะตรวจสอบว่าการตอบกลับจริงตรงกับประเภทข้อมูลที่ระบุไว้, ฟิลด์ที่จำเป็น และรหัสสถานะหรือไม่ คุณสร้างและดูแลสถานการณ์เหล่านั้นด้วยภาพ แทนที่จะเขียนสคริปต์ทดสอบชุดคู่ขนานด้วยมือที่อาจคลาดเคลื่อนไปจากสัญญาเมื่อมีการเปลี่ยนแปลง
เนื่องจาก Apidog รวมการออกแบบ, การจำลอง และการทดสอบไว้ในพื้นที่ทำงานเดียวกัน สเปคจึงเป็นแหล่งความจริงเดียวสำหรับทั้งหมด คุณสามารถ ดาวน์โหลด Apidog และนำเข้าสเปคที่มีอยู่เพื่อลองใช้งานลูปนี้กับ API ของคุณเอง หากคุณยังคงตัดสินใจว่าจะควบคุมสเปคนั้นอย่างไรในแต่ละเวอร์ชันตั้งแต่แรก บทความเกี่ยวกับ การควบคุมเวอร์ชัน OpenAPI spec ด้วย Git จะเข้ากันได้ดีกับเวิร์กโฟลว์นี้
Apidog CLI คือสิ่งที่จะรันสถานการณ์เหล่านั้นโดยไม่มีหัว (headless) ในไปป์ไลน์ของคุณ เป็นแพ็กเกจ npm:
npm install -g apidog-cli
คุณรันสถานการณ์ด้วย ID, ชี้ไปที่สภาพแวดล้อมที่คุณต้องการตรวจสอบ และขอรายงานที่เป็นมิตรกับ CI:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <scenarioId> \
-e <environmentId> \
-r junit,cli \
--out-dir ./apidog-reports
access token ใช้สำหรับการยืนยันตัวตนการรันและเก็บไว้ใน CI secret ไม่เคยอยู่ในไฟล์ที่คอมมิต แฟล็ก -t เลือกสถานการณ์, -e เลือกสภาพแวดล้อม และ -r junit,cli สร้าง XML ของ JUnit ที่เครื่องอ่านได้สำหรับแดชบอร์ด CI ของคุณ ควบคู่ไปกับผลลัพธ์เทอร์มินัลที่อ่านได้สำหรับบันทึกการสร้าง คุณไม่จำเป็นต้องเดา ID: คุณคัดลอกคำสั่งที่ถูกต้อง พร้อมด้วย ID สถานการณ์และสภาพแวดล้อมจริงที่กรอกไว้แล้ว จากแท็บ CI/CD ของสถานการณ์ใน Apidog หากคุณต้องการตัวเลือกทั้งหมด คู่มือ CLI ฉบับสมบูรณ์ จะบันทึกทุกแฟล็กไว้ และ apidog run --help จะพิมพ์ข้อมูลตามต้องการ
พฤติกรรมของเกตเป็นหลักการเดียวกับการทำ diff เมื่อการยืนยันล้มเหลว เนื่องจาก live response ไม่ตรงกับสัญญาอีกต่อไป apidog run จะออกด้วยค่าที่ไม่ใช่ศูนย์ CI อ่านรหัสออก, ทำเครื่องหมายว่าขั้นตอนล้มเหลว และบล็อกการผสาน ไม่มีการตั้งค่าเพิ่มเติม ตราบใดที่ขั้นตอนการรันอยู่ในไปป์ไลน์ การถดถอยของสัญญาจะหยุดสายการทำงานในลักษณะเดียวกับที่ breaking-change diff ทำ
ลำดับการดำเนินการก่อนการผสานที่สมบูรณ์
นำทั้งสองส่วนมารวมกัน คุณก็จะได้ไปป์ไลน์ที่สามารถจับความผิดพลาดได้ทั้งสองประเภท diff จะจับการเปลี่ยนแปลงที่อาจทำให้ไคลเอนต์เสียหายโดยการอ่านสเปค การทดสอบสัญญาจะจับบริการที่ไม่ได้ปฏิบัติตามสเปคอีกต่อไปโดยการใช้งาน API ที่กำลังทำงานอยู่ รันพวกมันเป็นงานแยกกัน:
jobs:
breaking-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- run: git show origin/${{ github.base_ref }}:openapi.yaml > base-openapi.yaml
- run: curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh
- run: oasdiff breaking base-openapi.yaml openapi.yaml --fail-on ERR
contract-conformance:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
- run: npm install -g apidog-cli
- name: Run contract tests
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: ./apidog-reports
ทั้งสองงานจะรันพร้อมกัน งาน diff จะอ่านไฟล์และไม่ต้องการอะไรนอกจาก git ดังนั้นจึงเสร็จสิ้นในไม่กี่วินาที งาน conformance ต้องการสภาพแวดล้อมที่สามารถเข้าถึงได้ ดังนั้นโดยปกติแล้วจะรันกับ staging build ที่ถูกปรับใช้ if: always() บนการอัปโหลดช่วยให้รายงานยังคงส่งอยู่เสมอแม้เมื่อการทดสอบล้มเหลว ซึ่งเป็นช่วงเวลาที่คุณต้องการอ่านมันมากที่สุด หากงานใดงานหนึ่งเป็นสีแดง PR จะถูกบล็อก สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการรัน CLI ในไปป์ไลน์จริง คู่มือ Apidog CLI GitHub Actions และ บทแนะนำไปป์ไลน์ CI/CD ที่ครอบคลุมกว่าจะเจาะลึกเกี่ยวกับการเชื่อมต่อ