Softonic

ตัวตรวจสอบ OpenAPI YAML

ขั้นตอน 1 / 2
ถัดไป

วาง openapi.yaml ของคุณ แล้วตัวตรวจสอบจะตรวจส่วนที่สเปคทุกฉบับต้องมี ได้แก่ ฟิลด์เวอร์ชัน อ็อบเจกต์ info ที่มี title และ version และอ็อบเจกต์ paths นอกจากนี้ยังเตือนเรื่องคีย์พาธที่ไม่ขึ้นต้นด้วยเครื่องหมายทับ และคีย์การดำเนินการที่ไม่รู้จัก

วิธีตรวจไฟล์ OpenAPI YAML

  1. 1

    คัดลอก YAML

    คัดลอกเนื้อหาทั้งหมดของ `openapi.yaml` หรือ `swagger.yaml` โดยรักษาการย่อหน้าให้เหมือนเดิมทุกประการ

  2. 2

    วางลงในช่องกรอก

    วางลงในช่องเอกสาร OpenAPI / Swagger ใน YAML การย่อหน้าคือโครงสร้างเอง จึงไม่ควรพิมพ์ใหม่หรือจัดวางใหม่

  3. 3

    เรียกการตรวจสอบ

    ไปยังขั้นตอนผลลัพธ์และอ่านข้อผิดพลาดกับคำเตือน

  4. 4

    แก้ไขและตรวจอีกครั้ง

    แก้รายการที่ถูกระบุในไฟล์ของคุณ แล้ววางเวอร์ชันใหม่และเรียกการตรวจอีกครั้ง

เหตุใดการย่อหน้าจึงมีผลต่อผลลัพธ์

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

ให้ใช้การเว้นวรรคแทนแท็บ และรักษาระยะย่อหน้าให้คงที่ เช่น สองช่องว่างต่อหนึ่งระดับ

ตัวอย่างการทำงาน

openapi: 3.0.3
info:
  title: Pets API
paths:
  /pets:
    get:
      summary: List pets

ฟิลด์เวอร์ชัน info.title และ paths มีอยู่ครบ /pets ขึ้นต้นด้วยเครื่องหมายทับ และ get เป็นเมธอดที่รู้จัก สิ่งที่ขาดไปมีเพียงอย่างเดียวคือ info.version รายงานจะแสดงดังนี้

สิ่งที่พบ ชนิด
info.version is required. ข้อผิดพลาด

เพิ่ม version: 1.0.0 ใต้ info โดยย่อหน้าสองช่องว่าง เอกสารก็จะถูกรายงานว่าโครงสร้างถูกต้อง

ทำให้เอกสารเรียบง่ายเพื่อให้อ่านได้น่าเชื่อถือ

การตรวจจะอ่านแมปปิง YAML ธรรมดาได้ดีที่สุด คือคู่ key: value ที่เรียบง่ายและซ้อนกันด้วยการย่อหน้าที่สม่ำเสมอ หากเอกสารที่มีฟีเจอร์ขั้นสูงของ YAML เช่น แองเคอร์หรือบล็อกหลายบรรทัด ถูกรายงานว่าอ่านไม่ได้หรือแสดงฟิลด์ที่หายไป ให้ลองใช้สำเนา JSON ของสเปคเดียวกันเพื่อยืนยันว่าปัญหาอยู่ที่เนื้อหาหรือที่ไวยากรณ์ YAML

ผลลัพธ์ที่สะอาดยืนยันเพียงโครงร่างเท่านั้น ไม่ได้แก้ลิงก์ $ref และไม่ได้ตรวจสคีมา

ขั้นตอนการทำงานที่ใช้ได้จริงสำหรับสเปค YAML

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

สุดท้าย โปรดจำว่ารายงานแสดงเฉพาะสิ่งที่การตรวจมองเห็นได้ ไฟล์ YAML ที่ผ่านการตรวจแปลว่าโครงร่างระดับบนสุดถูกต้อง แต่ไม่ได้หมายความว่าทุกการดำเนินการ สคีมา หรือการอ้างอิงภายในนั้นถูกต้อง

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

ใช้การเว้นวรรค YAML ไม่รับแท็บสำหรับการย่อหน้า และแท็บอาจทำให้เอกสารอ่านไม่ได้ หรือทำให้ฟิลด์ย้ายไปอยู่ผิดระดับ

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

การตรวจนี้ดูเพียงว่ามีฟิลด์ openapi หรือ swagger อยู่หรือไม่ ไม่ได้ดูค่า ดังนั้นทั้งแบบมีและไม่มีเครื่องหมายคำพูดผ่านได้เหมือนกัน อย่างไรก็ตาม การใส่ "2.0" ในเครื่องหมายคำพูดสำหรับ Swagger ยังเป็นนิสัยที่ดี

ได้ ข้อความจะถูกอ่านเป็น JSON ก่อน และหากไม่สำเร็จจึงอ่านเป็น YAML ดังนั้นทั้งสองรูปแบบใช้ได้ในช่องเดียวกัน

เครื่องมือที่เกี่ยวข้อง

ตัวสร้างการตั้งค่า Webpack

สร้าง webpack.config.js สำหรับ webpack 5 ทั้งแบบ JavaScript ล้วน React หรือ Vue พร้อม TypeScript, Babel, CSS หรือ Sass, รูปภาพ, HtmlWebpackPlugin, เซิร์ฟเวอร์สำหรับพัฒนา และคำสั่ง npm install

เครื่องแปลงฐานตัวเลข

แปลงตัวเลขระหว่างฐานสอง ฐานแปด ฐานสิบ ฐานสิบหก และฐานกำหนดเองตั้งแต่ 2 ถึง 36 พร้อมการแยกค่าประจำหลัก

ตัวแปลง Timestamp

แปลง timestamp ของ Unix ในหน่วยวินาทีหรือมิลลิวินาทีเป็นวันที่ที่อ่านง่ายในเขตเวลา UTC และเขตเวลาหลัก และแปลงวันที่กลับเป็นค่า epoch

อ้างอิงตัวอักษร HTML

รายการที่สามารถค้นหาได้ขององค์ประกอบ HTML พร้อมรหัสชื่อและรหัสตัวเลข รวมถึงฟังก์ชันสำเนาด้วยคลิกเดียวสำหรับตัวอักษรพิเศษและสัญลักษณ์ต่างๆ

ตารางอ้างอิง ASCII

ตาราง ASCII ครบตั้งแต่ 0 ถึง 127 พร้อมค่าเลขฐานสิบ ฐานสิบหก ฐานแปด ฐานสอง และรูปแบบการอ้างอิงอักขระแบบตัวเลขของ HTML รวม NUL, LF และ DEL

เครื่องสุ่มที่อยู่

สร้างระเบียนคล้ายที่อยู่ 1–20 รายการสำหรับแบบจำลองและการทดสอบ ด้วยรูปแบบประเทศแบบย่อ

เครื่องมือนี้มีให้บริการในภาษาอื่น

คู่มือและกรณีการใช้งาน