Softonic

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

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

วางเอกสาร OpenAPI 3.1 ในรูปแบบ JSON หรือ YAML เพื่อตรวจโครงสร้างระดับบนสุด เครื่องมือจะมองหาฟิลด์ openapi, อ็อบเจกต์ info ที่มี title และ version, และอ็อบเจกต์ paths นี่เป็นการตรวจโครงสร้าง จึงไม่ได้ตรวจคีย์เวิร์ดของสคีมา 3.1 และรูปแบบบางอย่างที่เหมาะกับ 3.1 อาจก่อให้เกิดคำเตือนหรือข้อผิดพลาดที่คุณควรทราบ

วิธีตรวจเอกสาร 3.1

  1. 1

    วางสเปค 3.1 ของคุณ

    วางเอกสารที่มี `openapi: 3.1.0` (หรือค่า 3.1.x อื่น) ลงในช่องกรอก ในรูปแบบ JSON หรือ YAML

  2. 2

    เริ่มการตรวจ

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

  3. 3

    อ่านหมายเหตุของ 3.1

    ตรวจว่ารายการที่ถูกแจ้งเป็นความผิดพลาดจริงหรือเป็นรูปแบบ 3.1 ที่อธิบายไว้ด้านล่าง

  4. 4

    ตรวจต่อด้วยลินเตอร์ฉบับเต็ม

    เมื่อโครงสร้างถูกต้องแล้ว ใช้เครื่องมือตรวจสอบฉบับเต็มเพื่อตรวจกฎของ JSON Schema 2020-12

เครื่องมือนี้ทำอะไรกับไฟล์ 3.1

เวอร์ชัน 3.1 ทำให้สคีมาสอดคล้องกับ JSON Schema 2020-12 ตัวตรวจสอบนี้ไม่อ่านเนื้อในของสคีมาเลย แต่ตรวจเฉพาะระดับบนสุดและรายการพาธ ดังนั้นคุณสมบัติสคีมาของ 3.1 เช่น อาร์เรย์ของชนิดข้อมูล หรือ const จะไม่ผ่านและไม่ตกที่นี่ นอกจากนี้ค่าของฟิลด์ openapi เองก็ไม่ได้ถูกตรวจ ฟิลด์ openapi ใดก็ตามจะถือว่ามีอยู่แล้ว

รูปแบบ 3.1 สองแบบที่ควรระวัง

รูปแบบในไฟล์ 3.1 ของคุณ สิ่งที่เครื่องมือรายงาน
อ็อบเจกต์ webhooks แต่ไม่มีอ็อบเจกต์ paths ข้อผิดพลาด: Missing ‘paths’ object.
การดำเนินการ trace ภายใต้พาธ คำเตือน: Unknown method ‘trace’ on the path
$ref เป็นคีย์ของรายการพาธ คำเตือน: Unknown method ‘$ref’ on the path

OpenAPI 3.1 อนุญาตให้อธิบายเฉพาะ webhooks และไม่ใส่ paths เครื่องมือนี้กำหนดให้ต้องมี paths ไฟล์แบบนั้นจึงถูกรายงานเป็นข้อผิดพลาด แม้สเปคจะอนุญาต การเพิ่มอ็อบเจกต์ paths: {} ที่ว่างเปล่าจะทำให้ผ่านการตรวจ

รายการเมธอดที่ใช้ที่นี่คือ get, post, put, patch, delete, head, options และ parameters, summary, description, servers เมธอด trace มีอยู่ในสเปค แต่ไม่อยู่ในรายการนี้ จึงทำให้เกิดคำเตือนที่คุณเพิกเฉยได้หากตั้งใจใช้ คำเตือนไม่ทำให้เอกสารไม่ถูกต้อง

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

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

ผลลัพธ์: ข้อผิดพลาดหนึ่งรายการคือ “Missing ‘paths’ object.” เพิ่ม paths: {} แล้วโครงสร้างจะผ่านการตรวจ

ควรใช้เครื่องมือนี้เมื่อใด และควรไปต่อเมื่อใด

ใช้หน้านี้เพื่อยืนยันว่าไฟล์ 3.1 มีโครงสร้างถูกต้องก่อนเปิด pull request หรือส่งให้พาร์ทเนอร์ การตรวจทำได้รวดเร็วและข้อความก็ชัดเจน เมื่อโครงสร้างถูกต้องแล้ว กฎของสคีมา 3.1 ยังต้องใช้ลินเตอร์ฉบับเต็ม เพราะข้อผิดพลาดจริงส่วนใหญ่อยู่ตรงนั้น เช่น การประกาศชนิดข้อมูลที่ไม่ถูกต้อง การอ้างอิงที่เสีย และนิยามการตอบกลับที่หายไป ให้มองสองขั้นตอนนี้เป็นสิ่งที่เสริมกัน ไม่ใช่ทางเลือกแทนกัน

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

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

ไม่ เครื่องมือไม่ดูข้างในอ็อบเจกต์สคีมา ดังนั้นคีย์เวิร์ดของ JSON Schema 2020-12 จึงไม่ได้รับการตรวจ เครื่องมือตรวจเฉพาะโครงสร้างระดับบนสุดและรายการพาธเท่านั้น

การตรวจกำหนดให้ต้องมีอ็อบเจกต์ paths ไฟล์ 3.1 ที่มีเฉพาะ webhooks ไม่มีอ็อบเจกต์นี้ จึงมีรายงานข้อผิดพลาดว่าไม่มี paths เพิ่ม paths: {} ที่ว่างเปล่าเพื่อให้ผ่าน

ไม่ เครื่องมือตรวจเพียงว่ามีฟิลด์ openapi หรือ swagger อยู่หรือไม่ ไม่ได้ตรวจค่าของฟิลด์

ไม่จำเป็นเสมอไป trace เป็นการดำเนินการที่ถูกต้องในสเปค เพียงแต่เครื่องมือไม่ได้รวมไว้ในรายการเมธอดที่รู้จัก

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

ตัวสร้างการตั้งค่า 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 รายการสำหรับแบบจำลองและการทดสอบ ด้วยรูปแบบประเทศแบบย่อ

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

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