ไฟล์ Swagger ที่เสียไม่ค่อยแสดงอาการเอง YAML ถูกแยกวิเคราะห์อย่างถูกต้อง หน้าเอกสารก็แสดงผลดี จากนั้นนักพัฒนาส่วนหน้าจะสร้างไคลเอนต์จากสเปกของคุณ บิลด์ล้มเหลวเนื่องจากฟิลด์ required หายไป และคุณก็พบว่าคำอธิบาย API ที่ “เสร็จสมบูรณ์” ของคุณมีข้อผิดพลาดในการพิมพ์ใน $ref เมื่อสามคอมมิตที่แล้ว สเปกนั้นผิดมาตลอด ไม่มีอะไรบอกคุณจนกระทั่งมันทำให้ใครบางคนเสียเวลาไปทั้งบ่าย
นั่นคืองานที่ตัวตรวจสอบ Swagger ทำ: มันอ่านไฟล์ OpenAPI หรือ Swagger ของคุณ และบอกคุณ ก่อนที่ใครจะนำไปใช้ ว่าเอกสารนั้นถูกต้องหรือไม่ ไม่ใช่แค่ “ดูเหมือนจะถูกไหม” แต่เป็น “สอดคล้องกับข้อกำหนด OpenAPI หรือไม่ แก้ไขการอ้างอิงทุกจุด และอธิบายสคีมาที่เครื่องมือเชื่อถือได้หรือไม่” ตัวตรวจสอบจะเปลี่ยนข้อผิดพลาดเชิงโครงสร้างที่เงียบงันให้กลายเป็นข้อผิดพลาดที่มีเสียงดังพร้อมระบุบรรทัด ซึ่งคุณสามารถแก้ไขได้ในไม่กี่วินาที แทนที่จะต้องดีบักปลายทางเป็นเวลาหลายชั่วโมง
สิ่งที่ตัวตรวจสอบ Swagger ตรวจสอบจริง ๆ
ก่อนอื่นคือเรื่องการตั้งชื่อ "Swagger" และ "OpenAPI" อธิบายสิ่งเดียวกันในจุดเวลาที่ต่างกันในประวัติศาสตร์ รูปแบบนี้ถูกเรียกว่า Swagger จนถึงเวอร์ชัน 2.0 จากนั้นได้บริจาคให้กับ OpenAPI Initiative และเปลี่ยนชื่อใหม่; เวอร์ชัน 3.0, 3.1 และ 3.2 ล้วนเป็น OpenAPI ผู้คนยังคงเรียก “swagger validator” ด้วยความเคยชิน และเครื่องมือส่วนใหญ่รองรับทั้ง Swagger 2.0 และ OpenAPI 3.x หากประวัติเวอร์ชันดูไม่ชัดเจน การเปรียบเทียบ Swagger กับ OpenAPI จะช่วยชี้แจงให้กระจ่าง สำหรับความแตกต่างระหว่างเวอร์ชันล่าสุด โปรดดู สิ่งที่เปลี่ยนแปลงใน OpenAPI 3.2 เทียบกับ 3.1 เทียบกับ 3.0
ตัวตรวจสอบจริง ๆ ทำงานสามอย่างตามลำดับ:
- แยกวิเคราะห์ (Parse). ไฟล์เป็น YAML หรือ JSON ที่ถูกต้องหรือไม่? แท็บที่ผิดที่, คีย์ที่ซ้ำกัน, วงเล็บที่ไม่ปิด, เอกสารจะโหลดไม่ได้ นี่เป็นข้อผิดพลาดที่แก้ไขได้ง่ายที่สุดและน่าอับอายที่สุดเมื่อส่งมอบงาน
- ตรวจสอบโครงสร้าง (Validate structure). เอกสารสอดคล้องกับสคีมา OpenAPI หรือไม่? ทุกการทำงานต้องมีออบเจกต์
responsesพารามิเตอร์ทุกตัวต้องมีค่าin$refต้องชี้ไปยังสิ่งที่มีอยู่ นี่คือที่ที่บั๊กจริงส่วนใหญ่ซ่อนอยู่ - แก้ไขการอ้างอิง (Resolve references). เอกสาร OpenAPI เต็มไปด้วยตัวชี้
$refที่เชื่อมโยงสคีมาที่นำกลับมาใช้ใหม่ได้เข้าด้วยกัน ตัวตรวจสอบจะติดตามทุกตัวและจะล้มเหลวหากเป้าหมายหายไป เป็นวงกลมในลักษณะที่สเปกห้าม หรือชี้ไปยังไฟล์ผิด
ผ่านทั้งสามขั้นตอน คุณก็จะได้เอกสารที่เครื่องมือที่สอดคล้องใด ๆ ก็ตาม, ตัวสร้างโค้ด, เซิร์ฟเวอร์จำลอง, ตัวแสดงเอกสาร, สามารถอ่านได้โดยไม่มีปัญหา หากล้มเหลวเพียงข้อเดียว ความล้มเหลวนั้นจะแสดงขึ้นในที่ที่ไม่สะดวกสบายเท่ากับในเทอร์มินัลของคุณ
ข้อผิดพลาดที่มันตรวจจับได้ซึ่งจะส่งผลในภายหลัง
การตรวจสอบความถูกต้องอาจดูเป็นนามธรรมจนกว่าคุณจะเห็นว่ามีอะไรเล็ดลอดผ่านไปได้โดยไม่มีมัน นี่คือข้อผิดพลาดของสเปกที่ดูเหมือนไม่เป็นอันตรายในตัวแก้ไข แต่กลับกลายเป็นเหตุการณ์จริงที่ปลายน้ำ
ตัวชี้ $ref ที่เสีย คุณเปลี่ยนชื่อสคีมาจาก User เป็น UserProfile แต่พลาดการอ้างอิงหนึ่งจุดที่อยู่ลึกเข้าไปในเนื้อหาการตอบกลับ YAML ยังคงแยกวิเคราะห์ได้ หน้าเอกสารยังคงแสดงส่วนที่เหลือของหน้า ตัวสร้างโค้ดไปเจอตัวชี้ที่ค้างอยู่และสร้างไคลเอนต์ที่มีชนิดข้อมูลหายไป หรือแค่พังไปเลย ตัวตรวจสอบจะแจ้งเตือน $ref ที่เสียทันทีที่คุณบันทึก
สคีมาและตัวอย่างไม่ตรงกัน สคีมาของคุณระบุว่า age เป็นจำนวนเต็ม; ตัวอย่างของคุณแสดง "age": "thirty" Swagger UI แสดงทั้งสองอย่างได้โดยไม่มีปัญหา เซิร์ฟเวอร์จำลองที่สร้างจากสเปกจะส่งกลับค่าสตริงในขณะที่ผู้ใช้งานคาดหวังตัวเลข และการทดสอบสัญญาที่อยู่ห่างออกไปสามทีมก็ขึ้นสีแดงด้วยเหตุผลที่ไม่มีใครสามารถย้อนกลับไปถึงไฟล์ของคุณได้
ส่วนประกอบที่จำเป็นขาดหายไป การทำงานที่ไม่มี responses พารามิเตอร์พาธที่ประกาศไว้ในเทมเพลต URL แต่ไม่เคยถูกนิยามใน parameters requestBody ที่ไม่มี content แต่ละอย่างถือเป็นเอกสารที่มีรูปแบบผิดพลาดในทางเทคนิค และแต่ละอย่างจะสร้างอาการปลายน้ำที่แตกต่างกันไป ขึ้นอยู่กับว่าเครื่องมือใดที่อ่านสเปกก่อน
ชนิดและรูปแบบคลาดเคลื่อน format: date-time บนฟิลด์ที่แบ็กเอนด์ส่งกลับมาเป็น Unix timestamp type: string บนสิ่งที่จริง ๆ แล้วเป็นอาร์เรย์ สิ่งเหล่านี้ผ่านการตรวจสอบโครงสร้าง แต่ละเมิดสัญญาซึ่งกันและกันระหว่างสเปกและ API ที่กำลังทำงานอยู่ ซึ่งเป็นปัญหาที่แยกต่างหากที่เราจะกล่าวถึงต่อไป
รูปแบบนี้สอดคล้องกัน: ข้อผิดพลาดของสเปกนั้นมองไม่เห็นในขณะที่คุณสร้างมัน และมีค่าใช้จ่ายสูงในขณะที่ผู้อื่นนำไปใช้ การตรวจสอบความถูกต้องจะย้ายต้นทุนกลับไปยังจุดที่ราคาถูก
วิธีการตรวจสอบไฟล์ Swagger ด้วยตนเอง
คุณไม่จำเป็นต้องมีแพลตฟอร์มเพื่อเริ่มต้น มีสามวิธีง่าย ๆ ในการตรวจสอบสเปกในวันนี้
Swagger Editor วาง YAML ของคุณลงใน Swagger Editor แล้วมันจะทำการตรวจสอบความถูกต้องในขณะที่คุณพิมพ์ โดยขีดเส้นใต้ข้อผิดพลาดพร้อมหมายเลขบรรทัดที่ขอบด้านขวา นี่เป็นวิธีที่เร็วที่สุดในการตรวจสอบความถูกต้องเบื้องต้นของไฟล์เดียว และไม่มีค่าใช้จ่าย ข้อจำกัดคือมันเป็นเพียงกล่องข้อความเดียว: มันตรวจสอบเอกสารแต่ไม่ได้ตรวจสอบว่า API จริงของคุณยังคงตรงกันหรือไม่ และคุณกำลังเขียน YAML ด้วยมือโดยไม่มีเครื่องมือสร้างสคีมาแบบภาพ สำหรับการเรียนรู้รูปแบบนั้นก็ดีแล้ว แต่สำหรับสเปกที่ทีมต้องพึ่งพา มันเป็นเพียงแท็บหนึ่งในขั้นตอนการทำงานที่ต้องใช้หลายแท็บ
เครื่องมือ Lint เช่น Spectral Spectral ของ Stoplight เป็น CLI แบบโอเพนซอร์สที่ตรวจสอบนอกเหนือจากความถูกต้องดิบ ๆ ไปจนถึงกฎเกณฑ์ด้านสไตล์ มันตรวจสอบความถูกต้องเชิงโครงสร้างและช่วยให้คุณบังคับใช้ชุดกฎได้: การทำงานทุกอย่างต้องมีคำอธิบาย, คุณสมบัติสคีมาทุกตัวต้องมีชนิดข้อมูล, การตั้งชื่อต้องเป็นไปตามแบบแผนของคุณ Spectral เป็นเครื่องมือที่ดีที่สุดในระดับเดียวกันสำหรับการควบคุม *สไตล์* ของสเปกในหลาย ๆ ไฟล์อย่างแท้จริง และหากการออกแบบ API ที่สอดคล้องกันเป็นสิ่งที่คุณกังวล ก็คุ้มค่าที่จะนำมาใช้ คุณเรียกใช้มันดังนี้:
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
ข้อแลกเปลี่ยนคือขอบเขต Spectral ตรวจสอบความถูกต้องและ Lint เอกสาร ไม่ใช่ตัวเรียกใช้คำขอ มันจะไม่บอกคุณว่า API ที่สเปกอธิบายนั้นทำงานตามที่สเปกกล่าวอ้างจริงหรือไม่ นั่นเป็นเลเยอร์ที่แตกต่างกัน และเป็นเลเยอร์ที่ความประหลาดใจส่วนใหญ่ในการผลิตอยู่
ปลายทางตัวตรวจสอบออนไลน์ โปรเจกต์ Swagger เผยแพร่บริการตัวตรวจสอบที่ส่งคืนป้าย "ผ่าน" หรือ "ไม่ผ่าน" สำหรับ URL สเปกที่โฮสต์ไว้ มันสะดวกสำหรับป้าย README แต่ไม่ค่อยเหมาะกับการวนแก้ไขแบบโต้ตอบ สำหรับข้อมูลเชิงลึกเพิ่มเติมเกี่ยวกับตัวเลือกแบบสแตนด์อโลน เราได้รวบรวม เครื่องมือตรวจสอบ OpenAPI ที่ดีที่สุด และคำแนะนำที่เน้นไปที่ วิธีการตรวจสอบ OpenAPI specs
ทั้งสามวิธีนี้ตรวจสอบเอกสารได้ ไม่มีวิธีใดที่เชื่อมช่องว่างระหว่างสเปกที่ถูกต้องกับ API ที่ถูกต้องได้ ช่องว่างนั้นคือสิ่งที่ส่วนถัดไปจะกล่าวถึง
Apidog เข้ามามีบทบาทอย่างไร: ตรวจสอบสเปก จากนั้นพิสูจน์ว่า API ตรงกับสเปก
Apidog เป็นแพลตฟอร์ม API แบบครบวงจร: คุณออกแบบสคีมา, ดีบักคำขอ, สร้างสถานการณ์ทดสอบอัตโนมัติ, จำลองปลายทาง, และเผยแพร่เอกสารในพื้นที่ทำงานเดียว การตรวจสอบสเปกไม่ใช่เครื่องมือแยกต่างหากที่คุณนำมาต่อเติม; แต่เป็นคุณสมบัติหนึ่งของการทำงานในแพลตฟอร์ม
เมื่อคุณนำเข้าไฟล์ Swagger หรือ OpenAPI หรือออกแบบในตัวแก้ไขแบบภาพ Apidog จะแยกวิเคราะห์และตรวจสอบความถูกต้องตั้งแต่แรกเริ่ม เอกสารที่มีรูปแบบผิดพลาด, $ref ที่เสีย, พารามิเตอร์ที่ไม่มีชนิดข้อมูล, สิ่งเหล่านี้จะปรากฏขึ้นในขณะที่คุณทำงาน ไม่ใช่หลังจากผ่านเครื่องมือปลายน้ำไปแล้วหลายตัว เนื่องจากตัวแก้ไขเป็นแบบภาพ ข้อผิดพลาดประเภท YAML ที่เขียนด้วยมือจะไม่เกิดขึ้นเลย: คุณไม่สามารถลืมค่า in ของพารามิเตอร์ได้เมื่อฟิลด์นั้นเป็นแบบดรอปดาวน์ที่จำเป็น สเปกนั้นถูกต้องตั้งแต่การสร้าง
นั่นเป็นการจัดการเอกสาร ปัญหาที่ยากกว่าคือความคลาดเคลื่อน (drift) ซึ่งเป็นความไม่ลงรอยกันอย่างช้าๆ ระหว่างสเปกที่บอกอย่างหนึ่งกับ API ที่ทำอีกอย่างหนึ่ง ตัวตรวจสอบแบบสแตนด์อโลนไม่สามารถตรวจจับสิ่งนี้ได้ เพราะไฟล์นั้นถูกต้อง; แต่เป็นบริการที่กำลังทำงานอยู่ต่างหากที่ผิดพลาด นี่คือโหมดความล้มเหลวที่อยู่เบื้องหลัง เอกสาร Swagger และ Postman collections ที่คลาดเคลื่อนจำนวนมาก
Apidog แก้ไขปัญหานี้โดยทำให้สเปกเป็นแหล่งความจริงสำหรับการทดสอบ คุณสร้าง สถานการณ์ทดสอบโดยตรงจาก OpenAPI spec ของคุณ จากนั้นยืนยันว่าการตอบสนองจริงตรงกับสคีมาที่คุณประกาศไว้ เมื่อสเปกระบุว่า age เป็นจำนวนเต็มและ API ส่งกลับสตริง การทดสอบจะล้มเหลว และมันล้มเหลวเทียบกับสเปก ไม่ใช่เทียบกับสำเนาที่ดูแลด้วยมือ คำถามของตัวตรวจสอบจะกลายเป็นคำถามต่อเนื่อง: ไม่ใช่ “ไฟล์นี้ถูกต้องเมื่อฉันบันทึกหรือไม่” แต่เป็น “API ที่ใช้งานจริงยังคงเป็นไปตามสัญญาหรือไม่” หากคุณต้องการกลไกการยืนยัน การยืนยัน API: คู่มือฉบับปฏิบัติ ครอบคลุมการตรวจสอบรูปแบบการตอบสนอง สถานะ และฟิลด์
สำหรับทีมที่ต้องการให้การตรวจสอบความถูกต้องถูกบังคับใช้โดยอัตโนมัติแทนที่จะต้องจำ Apidog ยังครอบคลุมถึง การรักษา API ให้เป็นไปตามมาตรฐาน OpenAPI ซึ่งเป็นส่วนหนึ่งของวงจรการออกแบบ
เรียกใช้การตรวจสอบที่ขับเคลื่อนด้วยสเปกใน CI ด้วย Apidog CLI
ตัวตรวจสอบที่ทำงานเฉพาะเมื่อมีคนเปิดตัวแก้ไขเท่านั้น คือตัวตรวจสอบที่จะถูกข้ามไปในที่สุด วิธีแก้ไขคือการนำการตรวจสอบความถูกต้องไปใส่ในไปป์ไลน์ ซึ่งจะทำงานทุกครั้งที่มีการพุชโดยไม่มีคนเข้ามาเกี่ยวข้อง นั่นคือสิ่งที่ Apidog command-line runner มีไว้เพื่อ
CLI เป็นแพ็คเกจ npm ที่ชื่อว่า apidog-cli มันรันสถานการณ์ทดสอบที่คุณสร้างใน Apidog โดยไม่ต้องมี UI จากสภาพแวดล้อมใด ๆ ที่มี Node.js ติดตั้งอยู่ ติดตั้งได้ด้วยคำสั่งเดียว:
npm install -g apidog-cli
จากนั้นรันสถานการณ์ที่บันทึกไว้ สถานการณ์เดียวกันที่ยืนยันว่าการตอบสนองสดของคุณตรงกับสเปก โดยใช้กับสภาพแวดล้อมหนึ่ง:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
ข้อสังเกตเล็กน้อยเกี่ยวกับสิ่งที่แฟล็กเหล่านั้นทำ -t คือรหัสสถานการณ์ทดสอบ -e คือรหัสสภาพแวดล้อม เพื่อให้คุณสามารถชี้การตรวจสอบเดียวกันไปยังสภาพแวดล้อม staging ใน pull request และไปยัง production หลังจากการปรับใช้ -r เลือกรูปแบบรายงาน: cli สำหรับเอาต์พุตบันทึกบิลด์ที่อ่านง่าย และคุณสามารถเพิ่ม html, json หรือ junit เพื่อป้อนข้อมูลไปยังแดชบอร์ด CI --access-token ควรอยู่ในความลับของ CI ไม่ควรอยู่ในโค้ดโดยตรง คุณสามารถสร้างทั้งโทเค็นและคำสั่งสำเร็จรูปได้จากแท็บ CI/CD ของสถานการณ์ภายใน Apidog สำหรับข้อมูลแฟล็กทั้งหมด ให้รัน apidog run --help หรืออ่าน คู่มือ Apidog CLI ฉบับเต็ม
รายละเอียดที่ทำให้สิ่งนี้เป็นด่านประตูจริง: CLI จะออกด้วยรหัสสถานะที่ไม่ใช่ศูนย์เมื่อการยืนยันล้มเหลว ระบบ CI จะอ่านรหัสสถานะนั้น การตรวจสอบสคีมาที่ล้มเหลวจะทำให้ขั้นตอนล้มเหลว ซึ่งทำให้งานล้มเหลว ซึ่งบล็อกการรวมโค้ด ดังนั้นทันทีที่ API ของคุณหยุดตรงกับสัญญา OpenAPI, บิลด์จะขึ้นสีแดง ก่อนที่การเปลี่ยนแปลงจะถูกส่งออกไป ไม่ใช่หลังจากผู้ใช้งานแจ้งปัญหา นั่นคือความแตกต่างระหว่างการตรวจสอบไฟล์ครั้งเดียวกับการตรวจสอบสัญญาในทุกคอมมิต พฤติกรรมรหัสออกเดียวกันนี้คือเหตุผลที่ตัวรันสามารถใช้ได้กับแพลตฟอร์ม CI ใดก็ได้ เช่นเดียวกับการ รัน Postman collections ใน CI โดยไม่ต้องใช้ Newman
ดาวน์โหลด Apidog หากคุณต้องการการตรวจสอบสเปกและการทดสอบสัญญาในที่เดียวกับที่ทีมของคุณออกแบบ API อยู่แล้ว
ขั้นตอนการทำงานการตรวจสอบที่ใช้งานได้จริง
เมื่อนำส่วนต่างๆ มารวมกัน นี่คือลำดับที่ตรวจจับข้อผิดพลาดของสเปกได้ในทุกขั้นตอน แทนที่จะเป็นเพียงขั้นตอนสุดท้าย:
- ออกแบบหรือนำเข้าในตัวแก้ไขที่มีการตรวจสอบความถูกต้อง ไม่ว่าคุณจะนำเข้าไฟล์ Swagger ที่มีอยู่ หรือสร้างมันในตัวออกแบบภาพของ Apidog เอกสารจะถูกแยกวิเคราะห์และตรวจสอบโครงสร้างตั้งแต่แรกเริ่ม การอ้างอิงที่เสียและชนิดข้อมูลที่หายไปจะปรากฏขึ้นทันที
- Lint เพื่อสไตล์หากคุณมีชุดกฎ หากองค์กรของคุณบังคับใช้กฎการตั้งชื่อและคำอธิบาย ให้รัน Spectral เป็นการตรวจสอบ pre-commit ที่รวดเร็ว ความถูกต้องและสไตล์ขององค์กรเป็นคนละเรื่องกัน; ครอบคลุมทั้งสองอย่าง
- สร้างการทดสอบจากสเปก เปลี่ยนเอกสาร OpenAPI ให้เป็นสถานการณ์ทดสอบ เพื่อให้การยืนยันของคุณเชื่อมโยงกับคำนิยามเดียวกันที่คุณส่งมอบ ไม่ใช่สำเนาแยกต่างหากที่คลาดเคลื่อนไป
- ควบคุมทุกการพุชด้วย CLI เชื่อม
apidog runเข้ากับไปป์ไลน์ของคุณ เพื่อให้ความไม่ตรงกันระหว่างสเปกกับความเป็นจริงทำให้บิลด์ล้มเหลวโดยอัตโนมัติ - ถือว่าสเปกเป็นแหล่งความจริง เมื่อการออกแบบเปลี่ยนไป การทดสอบจะชี้ไปยังไฟล์เดียวกัน ดังนั้นจึงไม่มีอะไรที่ต้องซิงค์ด้วยตนเอง
ขั้นตอนที่ 1 และ 2 ตรวจสอบเอกสาร ขั้นตอนที่ 3 ถึง 5 ตรวจสอบสัญญา คุณต้องมีทั้งสองอย่าง และที่ที่ถูกที่สุดในการทำทั้งหมดนี้คือพื้นที่ทำงานเดียว แทนที่จะเป็นสี่แท็บเบราว์เซอร์
ฉบับย่อ
ตัวตรวจสอบ Swagger ตรวจจับบั๊กโครงสร้าง, การอ้างอิงที่เสีย, ชนิดข้อมูลที่หายไป, YAML ที่มีรูปแบบผิดพลาด ซึ่งมองไม่เห็นในขณะที่คุณเขียน และมีค่าใช้จ่ายสูงเมื่อผู้อื่นอ่านมัน การตรวจสอบเอกสารคือพื้นฐาน ไม่ใช่เพดาน ข้อผิดพลาดที่ไปถึงเวอร์ชันที่ใช้งานจริงคือข้อผิดพลาดที่สเปกที่ถูกต้องหยุดตรงกับ API ที่เปลี่ยนแปลงไปอย่างเงียบๆ และตัวตรวจสอบระดับไฟล์ไม่สามารถมองเห็นสิ่งเหล่านั้นได้
วิธีแก้ไขคือการตรวจสอบความถูกต้องในสองชั้น และรวมทั้งสองชั้นไว้ในที่เดียว: ตรวจสอบเอกสารในขณะที่คุณออกแบบ จากนั้นตรวจสอบสัญญาในทุกการพุชโดยการยืนยันการตอบสนองจริงเทียบกับสเปก Apidog ทำอย่างแรกโดยการสร้าง และอย่างที่สองผ่านสถานการณ์ที่ตัวรัน apidog-cli ควบคุมใน CI สเปกยังคงเป็นแหล่งความจริง บิลด์จะขึ้นสีแดงทันทีที่ความเป็นจริงคลาดเคลื่อนจากมัน และไฟล์ Swagger ที่เสียก็จะไม่ใช่สิ่งที่คุณเพิ่งค้นพบเมื่อสายเกินไปในบ่ายวันหนึ่งอีกต่อไป