OpenAPI specification คือสัญญา ตัวสร้างโค้ดจะอ่านมัน เอกสารจะถูกสร้างจากมัน เซิร์ฟเวอร์จำลองจะทำงานบนมัน และ SDK ฝั่งไคลเอ็นต์จะถูกผลิตจากมัน เมื่อสเปคผิดพลาด ผลลัพธ์ปลายทางเหล่านี้ก็จะได้รับข้อผิดพลาดนั้นไปด้วย ตัวตรวจสอบความถูกต้องจะจับปัญหาในไฟล์สเปคได้ก่อนที่มันจะแพร่กระจาย บทความนี้ครอบคลุมเครื่องมือตรวจสอบความถูกต้องของ OpenAPI ที่คุ้มค่าแก่การใช้งาน แต่ละเครื่องมือมีจุดเด่นอย่างไร และจะเข้ากับขั้นตอนการทำงานจริงได้อย่างไร บางเครื่องมือจะตรวจสอบไวยากรณ์ดิบๆ ส่วนเครื่องมืออื่นๆ จะบังคับใช้กฎเกณฑ์ด้านสไตล์และการออกแบบ การตั้งค่าที่ดีที่สุดมักจะรวมทั้งสองอย่างเข้าด้วยกัน และคู่มือนี้จะอธิบายวิธีการประกอบเข้าด้วยกัน
ทำไมการตรวจสอบความถูกต้องของสเปคจึงสำคัญ
ตัวตรวจสอบความถูกต้องจะแก้ไขปัญหาที่แตกต่างกันสองอย่าง และการรวมเข้าด้วยกันอาจทำให้เกิดความสับสน อย่างแรกคือความถูกต้อง ไฟล์นั้นเป็น OpenAPI ที่ถูกต้องหรือไม่? บล็อก YAML ที่เยื้องผิด, `$ref` ที่ชี้ไปยังที่ที่ไม่ถูกต้อง, การตอบกลับที่ขาด `description` ที่จำเป็น, สคีมาที่มีการพิมพ์ผิดในชื่อประเภท สิ่งเหล่านี้คือข้อผิดพลาดเชิงวัตถุวิสัย ไฟล์จะถูกวิเคราะห์เทียบกับสคีมา OpenAPI ได้หรือไม่ ตัวตรวจสอบความถูกต้องจะให้คำตอบว่าใช่หรือไม่ อย่างที่สองคือคุณภาพ สเปคถูกต้องแล้ว แต่ดีหรือไม่? ทุกการทำงานควรมีสรุป ชื่อพาธควรสอดคล้องกัน ทุกการตอบกลับเมื่อเกิดข้อผิดพลาดควรได้รับการจัดทำเป็นเอกสาร ควรประกาศการรักษาความปลอดภัย สิ่งเหล่านี้ไม่มีข้อกำหนดในสคีมา OpenAPI แต่การละเลยจะสร้างสเปคที่ถูกต้องทางเทคนิคแต่ใช้งานยาก ตัววิเคราะห์โค้ด (linter) จะบังคับใช้กฎเกณฑ์การออกแบบเหล่านี้ การแก้ไขปัญหาทั้งสองประเภทตั้งแต่เนิ่นๆ นั้นถูกกว่าการแก้ไขหลังจาก SDK ถูกเผยแพร่ ซึ่งเป็นตรรกะเดียวกันกับการทดสอบสัญญา API โดยรวม
เครื่องมือตรวจสอบความถูกต้องที่น่าสนใจ
Swagger Editor
Swagger Editor คือตัวแก้ไขบนเบราว์เซอร์อย่างเป็นทางการจากโครงการ OpenAPI คุณสามารถวางหรือเขียนสเปคของคุณทางด้านซ้ายและดูข้อผิดพลาดในการตรวจสอบพร้อมการแสดงตัวอย่างที่แสดงผลแบบเรียลไทม์ทางด้านขวา เป็นวิธีที่เร็วที่สุดในการตรวจสอบว่าสเปคถูกต้องตามหลักไวยากรณ์หรือไม่ โดยไม่ต้องตั้งค่าใดๆ เลย เหมาะอย่างยิ่งสำหรับการแก้ไขและตรวจสอบด่วน แต่ไม่เหมาะสำหรับการรันในไปป์ไลน์อัตโนมัติ Swagger Editor นั้นฟรีและทำงานทั้งหมดในเบราว์เซอร์
Spectral
Spectral จาก Stoplight เป็นลินเตอร์ที่ทีมส่วนใหญ่เลือกใช้เพื่อบังคับใช้คุณภาพ มันมาพร้อมกับชุดกฎสำหรับ OpenAPI และ AsyncAPI และคุณค่าที่แท้จริงคือการกำหนดกฎที่กำหนดเอง คุณสามารถเขียนกฎใน YAML หรือ JavaScript เพื่อบังคับใช้หลักปฏิบัติของคุณเอง เช่น กำหนดให้ทุกการทำงานต้องมีคำอธิบาย หรือห้ามใช้เครื่องหมายทับท้ายในพาธ มันทำงานจากคอมมานด์ไลน์ ทำให้เหมาะอย่างยิ่งสำหรับ CI โครงการ Spectral เป็นโอเพ่นซอร์ส
openapi-spec-validator
openapi-spec-validator เป็นเครื่องมือ Python ที่เน้นทำสิ่งเดียวได้ดี: ตรวจสอบสเปคเทียบกับสคีมา OpenAPI อย่างเป็นทางการสำหรับเวอร์ชัน 2.0, 3.0 และ 3.1 มันไม่มีความเห็นเกี่ยวกับสไตล์ มันบอกคุณว่าไฟล์นั้นถูกต้องตามโครงสร้างหรือไม่ ในฐานะไลบรารีหรือ CLI มันสามารถรวมเข้ากับขั้นตอนการบิลด์ที่ใช้ Python และ pre-commit hooks ได้อย่างง่ายดาย เมื่อคุณต้องการประตูตรวจสอบความถูกต้องที่ต้องผ่านหรือไม่ผ่านเท่านั้น นี่คือตัวเลือกที่ชัดเจน
Apidog
Apidog ตรวจสอบความถูกต้องของสเปคในฐานะส่วนหนึ่งของขั้นตอนการทำงานการออกแบบแบบรวม ในขณะที่คุณสร้างหรือนำเข้าคำจำกัดความ OpenAPI มันจะระบุปัญหาเชิงโครงสร้างในตัวแก้ไข คุณสมบัติที่โดดเด่นกว่าคือการตรวจสอบรันไทม์: มันตรวจสอบการตอบกลับ API แบบเรียลไทม์เทียบกับสคีมาที่ประกาศในสเปคของคุณ เพื่อให้คุณตรวจจับความคลาดเคลื่อนที่การใช้งานไม่ตรงกับสัญญาอีกต่อไปได้ นั่นช่วยอุดช่องว่างระหว่างเอกสารที่ถูกต้องกับ API ที่ถูกต้อง ดาวน์โหลด Apidog เพื่อออกแบบและตรวจสอบสเปคในเครื่องมือเดียว
Redocly CLI
Redocly CLI รวมการวิเคราะห์โค้ด การตรวจสอบความถูกต้อง และการสร้างเอกสาร มันตรวจสอบเทียบกับสคีมา OpenAPI มาพร้อมกับชุดกฎที่กำหนดค่าได้ และสามารถรวมสเปคหลายไฟล์ให้เป็นชุดเดียวได้ ทีมที่สร้างเอกสารด้วย Redoc อยู่แล้วจะได้รับการตรวจสอบความถูกต้องในชุดเครื่องมือเดียวกันโดยไม่ต้องเพิ่มการพึ่งพาอื่นๆ
Vacuum
Vacuum เป็นลินเตอร์ OpenAPI ที่รวดเร็วซึ่งเขียนด้วย Go จุดเด่นคือความเร็วในการจัดการสเปคขนาดใหญ่มาก ซึ่งลินเตอร์ที่ใช้ JavaScript บางตัวอาจทำงานช้าลง มันเข้ากันได้กับกฎสไตล์ Spectral ดังนั้นทีมสามารถเปลี่ยนไปใช้ได้โดยไม่ต้องทำงานซ้ำมากนัก สำหรับ monorepo ที่มี API Surface ขนาดใหญ่ ความแตกต่างด้านประสิทธิภาพเป็นที่สังเกตได้
ตารางเปรียบเทียบ
| เครื่องมือ | ประเภท | ตรวจสอบ | ทำงานใน CI | เหมาะสำหรับ |
|---|---|---|---|---|
| Swagger Editor | ตัวแก้ไขในเบราว์เซอร์ | ไวยากรณ์, สคีมา | ไม่ | การแก้ไขแบบเรียลไทม์และตรวจสอบด่วน |
| Spectral | ลินเตอร์ CLI | สไตล์, กฎที่กำหนดเอง | ใช่ | การบังคับใช้หลักปฏิบัติในการออกแบบ |
| openapi-spec-validator | CLI / ไลบรารี Python | ความถูกต้องของสคีมา | ใช่ | ประตูตรวจสอบที่ต้องผ่านหรือไม่ผ่านเท่านั้น |
| Apidog | แพลตฟอร์มแบบรวม | สคีมา + ความคลาดเคลื่อนขณะรันไทม์ | ใช่ | การออกแบบบวกกับการตรวจสอบการตอบกลับ |
| Redocly CLI | CLI | สคีมา, สไตล์, การรวม | ใช่ | เอกสารและการตรวจสอบร่วมกัน |
| Vacuum | ลินเตอร์ CLI | สไตล์, กฎ Spectral | ใช่ | สเปคขนาดใหญ่มาก, ความเร็ว |
วิธีประกอบขั้นตอนการตรวจสอบความถูกต้อง
คุณไม่ได้เลือกใช้เครื่องมือเดียว คุณซ้อนทับกัน เริ่มต้นจากจุดที่คุณแก้ไข ขณะเขียนสเปค ให้ใช้ Swagger Editor หรือแพลตฟอร์มแบบรวม เพื่อให้ข้อผิดพลาดปรากฏขึ้นขณะที่คุณพิมพ์ สิ่งนี้จะจับข้อผิดพลาดที่เห็นได้ชัดได้ทันทีและถูกกว่าการแก้ไขในภายหลังมาก เพิ่มประตูตรวจสอบความถูกต้องใน CI รัน openapi-spec-validator หรือเครื่องมือ CLI ที่เทียบเท่าบนทุกพูลรีเควสต์ที่เกี่ยวข้องกับสเปค หากไฟล์ไม่ผ่านการตรวจสอบเทียบกับสคีมา OpenAPI บิลด์จะล้มเหลว นี่เป็นสิ่งที่ไม่สามารถต่อรองได้และเป็นแบบไบนารี เพิ่มประตูตรวจสอบคุณภาพถัดจากนั้น รัน Spectral หรือ Vacuum สำหรับสเปคขนาดใหญ่ ด้วยชุดกฎที่ทีมของคุณตกลงกัน เริ่มต้นด้วยกฎ OpenAPI ที่มีมาให้ จากนั้นเพิ่มกฎที่กำหนดเองสำหรับหลักปฏิบัติของคุณเอง เก็บชุดกฎไว้ในการควบคุมเวอร์ชันเพื่อให้มันพัฒนาไปพร้อมกับ API นี่คือหลักการเดียวกันที่ทำให้การทำให้การทดสอบเป็นไปโดยอัตโนมัติใน CI/CD น่าเชื่อถือ: การตรวจสอบจะทำงานทุกครั้ง ไม่ใช่เมื่อมีคนจำได้ สุดท้าย ตรวจสอบ API ที่กำลังทำงานเทียบกับสเปค สเปคอาจสมบูรณ์แบบในขณะที่การใช้งานได้คลาดเคลื่อนไปจากมัน การตรวจสอบรันไทม์ ไม่ว่าจะผ่าน Apidog หรือการทดสอบสัญญาในชุดทดสอบของคุณ ยืนยันว่า API ยังคงตรงกับสัญญา สำหรับด้านการทดสอบ การเขียนคำยืนยัน API ที่มีประโยชน์ ครอบคลุมวิธีการตรวจสอบการตอบกลับเทียบกับสคีมาที่จัดทำเป็นเอกสาร
ข้อผิดพลาดทั่วไป: ตรวจสอบเพียงครั้งเดียว
หลายทีมตรวจสอบสเปคเพียงครั้งเดียวเมื่อเขียนครั้งแรก จากนั้นก็ไม่ตรวจสอบอีกเลย สเปคจะเสื่อมโทรมลงจากตรงนั้น นักพัฒนาเพิ่มเอนด์พอยต์ในโค้ดและลืมสเปคไป บางคนปรับเปลี่ยนรูปร่างการตอบกลับ หกเดือนต่อมา สเปคอธิบายถึง API ที่ไม่มีอยู่อีกต่อไป และ SDKs และเอกสารที่สร้างขึ้นมาก็ผิดพลาดอย่างเงียบๆ การตรวจสอบต้องต่อเนื่อง ผนวกเข้ากับ CI เพื่อให้ทุกการเปลี่ยนแปลงสเปคถูกตรวจสอบ และทุกการเปลี่ยนแปลง API ถูกตรวจสอบเทียบกับสเปค ปฏิบัติต่อความล้มเหลวของสเปคเหมือนกับที่คุณปฏิบัติต่อ unit test ที่ล้มเหลว: บิลด์ไม่ผ่าน หลักการเดียวกันกับการทดสอบอัตโนมัติโดยทั่วไป ซึ่งก็คือการตรวจสอบจะมีค่าก็ต่อเมื่อมันทำงานโดยไม่ต้องมีใครตัดสินใจสั่งให้ทำงาน นอกจากนี้ การตรวจสอบกับเวอร์ชัน OpenAPI ที่ถูกต้องก็ช่วยได้ การเปิดตัว 3.1 ได้ปรับ OpenAPI ให้สอดคล้องกับ JSON Schema ซึ่งเปลี่ยนแปลงพฤติกรรมของโครงสร้างสคีมาบางอย่าง หากเครื่องมือของคุณถือว่า 3.0 แต่สเปคของคุณประกาศ 3.1 คุณอาจได้รับผลลัพธ์ที่ทำให้เข้าใจผิด OpenAPI Specification อย่างเป็นทางการบันทึกความแตกต่างของเวอร์ชัน และตัวตรวจสอบส่วนใหญ่ให้คุณสามารถระบุเวอร์ชันได้อย่างชัดเจน
สิ่งที่ตัวตรวจสอบจับได้แต่คุณอาจพลาด
ควรจะมีความชัดเจนเกี่ยวกับประเภทของปัญหาที่การตรวจสอบเผยให้เห็น เพราะ "สเปคผิด" เป็นคำที่คลุมเครือเกินไปที่จะดำเนินการ ข้อผิดพลาดเชิงโครงสร้างเป็นสิ่งที่เข้าใจง่ายที่สุด `$ref` ที่ชี้ไปยังสคีมาที่ไม่มีอยู่ อ็อบเจกต์การตอบกลับที่ไม่มี `description` ซึ่ง OpenAPI กำหนดไว้ พารามิเตอร์พาธที่ประกาศในเทมเพลต URL แต่ไม่เคยถูกกำหนดในรายการ `parameters` สคีมาที่ระบุ `type: integer` แต่ตัวอย่างแสดงเป็นสตริง ตัวตรวจสอบความถูกต้องจะระบุข้อผิดพลาดเหล่านี้ทั้งหมด และแต่ละข้อผิดพลาดจะทำให้ตัวสร้างโค้ดเสียหายหรือสร้าง SDK ที่ใช้งานไม่ได้ ปัญหาด้านคุณภาพมีความละเอียดอ่อนและพบได้บ่อยกว่า การทำงานที่ไม่มี `operationId` ซึ่งทำให้ชื่อเมธอดของไคลเอ็นต์ที่สร้างขึ้นดูไม่ดีหรือไม่เสถียร การใช้ตัวพิมพ์เล็ก-ใหญ่ในพาธที่ไม่สอดคล้องกัน โดยบางเส้นทางใช้ `snake_case` และบางเส้นทางใช้ `camelCase` เอนด์พอยต์ที่ระบุเอกสารการตอบกลับ 200 แต่ไม่เคยระบุ 400 หรือ 401 ทำให้ผู้ใช้งานไม่ทราบว่าข้อผิดพลาดมีลักษณะอย่างไร เนื้อหาคำขอถูกระบุว่าเป็นทางเลือกในขณะที่ API ต้องการจริงๆ ไม่มีสิ่งเหล่านี้ที่ทำให้ตัวแยกวิเคราะห์เสียหาย แต่ทั้งหมดทำให้ API ใช้งานยากขึ้น และลินเตอร์คือสิ่งที่รักษามาตรฐาน การเชื่อมโยงกับพฤติกรรมจริงคือสิ่งที่การทดสอบสัญญา API ตรวจสอบเมื่อสเปคเองสะอาดแล้ว
การนำการตรวจสอบเข้าสู่ขั้นตอนการทำงานแบบ Design-first
หลายทีมในปัจจุบันออกแบบ API ก่อนเขียนโค้ด โดยสร้างสเปค OpenAPI ก่อนและสร้าง server stubs, mocks และเอกสารจากมัน การตรวจสอบความถูกต้องมีความสำคัญมากยิ่งขึ้นในโมเดลนั้น เพราะสเปคไม่ใช่เอกสารของ API ที่มีอยู่; มันคือแหล่งความจริงที่ทุกสิ่งสร้างขึ้นจากมัน ข้อบกพร่องในสเปคกลายเป็นข้อบกพร่องในเซิร์ฟเวอร์ที่สร้างขึ้น ในขั้นตอนการทำงานแบบ design-first ให้ตรวจสอบตั้งแต่ช่วงออกแบบ การตรวจสอบระดับ Editor จับข้อผิดพลาดได้ในขณะที่สเปคกำลังก่อร่างสร้างตัว ก่อนที่การสร้างโค้ดใดๆ จะทำงาน จากนั้นเกต CI ยืนยันว่าไม่มีอะไรถดถอย เนื่องจากสเปคยังขับเคลื่อนเซิร์ฟเวอร์จำลองด้วย สเปคที่สะอาดหมายถึงม็อกทำงานได้อย่างถูกต้อง ซึ่งช่วยให้ทีมฟรอนต์เอนด์และไคลเอ็นต์สามารถสร้างโดยอิงจากตัวแทนที่เชื่อถือได้ หากคุณต้องการดูว่าสเปคมีผลต่อการจำลองอย่างไร คู่มือของเราเรื่องการจำลอง API สำหรับการทดสอบ จะแสดงให้เห็นถึงการเชื่อมโยง วินัยนี้คุ้มค่าในตัวเอง: ทุกชั่วโมงที่ใช้ในการรักษาสเปคให้ถูกต้องจะช่วยประหยัดเวลาหลายชั่วโมงในการแก้ไขจุดบกพร่องของไคลเอ็นต์ที่ไม่ตรงกันในภายหลัง
คำถามที่พบบ่อย
ความแตกต่างระหว่างตัวตรวจสอบ OpenAPI และลินเตอร์คืออะไร?
ตัวตรวจสอบจะตรวจสอบว่าสเปคถูกต้องตามโครงสร้างเทียบกับสคีมา OpenAPI หรือไม่ โดยให้คำตอบว่าผ่านหรือไม่ผ่าน ส่วนลินเตอร์จะตรวจสอบคุณภาพและสไตล์ เช่น ว่าทุกการทำงานมีคำอธิบายหรือไม่ หรือการตั้งชื่อพาธสอดคล้องกันหรือไม่ เครื่องมือหลายอย่างทำได้ทั้งสองอย่าง แต่ตอบคำถามที่แตกต่างกัน และขั้นตอนการทำงานที่แข็งแกร่งจะใช้ทั้งสองอย่าง
ฉันสามารถตรวจสอบสเปค OpenAPI ได้ฟรีหรือไม่?
ได้ Swagger Editor, Spectral, openapi-spec-validator, Redocly CLI และ Vacuum ล้วนเป็นเครื่องมือฟรีและโอเพ่นซอร์ส Apidog ตรวจสอบสเปคในระดับฟรีและเพิ่มการตรวจสอบรันไทม์ ไม่มีเหตุผลที่จะละเลยการตรวจสอบด้วยเหตุผลด้านค่าใช้จ่าย
ฉันควรตรวจสอบ OpenAPI 3.0 และ 3.1 แตกต่างกันหรือไม่?
คุณตรวจสอบด้วยเครื่องมือเดียวกัน แต่ต้องระบุเวอร์ชัน OpenAPI 3.1 ได้ปรับให้สอดคล้องกับ JSON Schema และเปลี่ยนแปลงพฤติกรรมของสคีมาบางอย่าง ดังนั้นตัวตรวจสอบที่คาดหวัง 3.0 อาจรายงานข้อผิดพลาดปลอมบนสเปค 3.1 ตรวจสอบให้แน่ใจว่าเครื่องมือของคุณรองรับเวอร์ชันที่สเปคของคุณประกาศไว้
การตรวจสอบสเปคควรทำงานที่ไหน?
ในสองที่: แบบเรียลไทม์ใน Editor ของคุณขณะเขียนสเปค เพื่อให้ข้อผิดพลาดปรากฏขึ้นทันที และใน CI สำหรับทุกพูลรีเควสต์ เพื่อไม่ให้มีการรวมอะไรเข้าด้วยกันพร้อมสเปคที่เสียหรือมีคุณภาพต่ำ การตรวจสอบเฉพาะใน Editor นั้นง่ายต่อการละเว้น แต่การตรวจสอบใน CI ไม่ใช่
ฉันจะตรวจสอบได้อย่างไรว่า API ของฉันตรงกับสเปค?
การตรวจสอบสเปคเพียงแค่ยืนยันว่าเอกสารถูกต้อง ไม่ใช่ว่าการใช้งานตรงกัน เพื่อจับความคลาดเคลื่อน ให้รันการทดสอบสัญญาหรือการตรวจสอบรันไทม์ที่เปรียบเทียบการตอบกลับ API แบบเรียลไทม์กับสคีมาในสเปค Apidog ทำสิ่งนี้โดยตรง และเฟรมเวิร์กการทดสอบสัญญาทำได้ในชุดทดสอบ