Softonic

ตัวตรวจสอบ OpenAPI

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

วางเอกสาร OpenAPI หรือ Swagger แบบ JSON หรือ YAML แล้วตัวตรวจสอบนี้จะตรวจโครงสร้างหลักของมัน โดยยืนยันว่าเอกสาร parse ได้ มีฟิลด์เวอร์ชัน openapi หรือ swagger มีออบเจกต์ info ที่มี title และ version และมีออบเจกต์ paths จากนั้นจะชี้ path ที่ไม่ได้ขึ้นต้นด้วยสแลชและเมธอด HTTP ที่ไม่รู้จัก นี่คือการตรวจโครงสร้างอย่างรวดเร็ว ไม่ใช่ตัวตรวจสอบ JSON Schema แบบเต็ม

ขั้นตอนการตรวจสอบเป็นอย่างไร

  1. 1

    วางเอกสาร

    JSON หรือ YAML สำหรับ OpenAPI 2 (Swagger) หรือ OpenAPI 3

  2. 2

    parse เอกสาร

    ตัวตรวจสอบจะ parse เอกสารเป็น JSON และย้อนไป parse แบบ YAML หากไม่สำเร็จ

  3. 3

    ตรวจฟิลด์ที่จำเป็น

    ยืนยันว่ามีฟิลด์เวอร์ชัน `openapi` หรือ `swagger` มีออบเจกต์ `info` ที่มี `title` และ `version` และมีออบเจกต์ `paths`

  4. 4

    สแกน path

    แต่ละ path จะถูกตรวจว่ามีสแลชนำหน้าหรือไม่ และแต่ละคีย์ของ operation จะถูกตรวจเทียบกับเมธอด HTTP ที่รู้จัก

  5. 5

    อ่านรายงาน

    ข้อผิดพลาดทำให้ไม่ผ่าน ส่วนคำเตือนจะชี้ path ที่ไม่มีสแลชนำหน้าและเมธอดที่ไม่รู้จัก

ตัวตรวจสอบนี้ตรวจอะไรบ้าง

การตรวจ ผลเมื่อไม่ผ่าน
เอกสาร parse เป็น JSON หรือ YAML ได้ ข้อผิดพลาด
มีฟิลด์ openapi หรือ swagger ข้อผิดพลาด
มีออบเจกต์ info ข้อผิดพลาด
มี info.title ข้อผิดพลาด
มี info.version ข้อผิดพลาด
มีออบเจกต์ paths ข้อผิดพลาด
แต่ละ path ขึ้นต้นด้วย / คำเตือน
คีย์ของ operation เป็นเมธอด HTTP ที่รู้จัก คำเตือน

เอกสารที่ผ่านทุกข้อผิดพลาดจะถูกรายงานว่าถูกต้องเชิงโครงสร้าง คำเตือนไม่ทำให้ไม่ผ่าน แต่ชี้จุดที่ควรแก้ไข

สิ่งที่ตัวตรวจสอบนี้ไม่ตรวจ

นี่คือการตรวจโครงสร้าง ไม่ใช่ตัวตรวจสอบสเปกแบบเต็ม มันไม่:

  • ตรวจทุกโหนดเทียบกับ JSON Schema ทางการสำหรับเวอร์ชันของคุณ
  • แก้ไขการอ้างอิง $ref หรือยืนยันว่าคอมโพเนนต์ที่มันชี้ไปมีอยู่จริง
  • ตรวจว่าพารามิเตอร์ของ path ถูกประกาศและใช้อย่างสอดคล้องกัน
  • ยืนยันว่าค่า operationId มีอยู่หรือไม่ซ้ำกัน
  • รายงานหมายเลขบรรทัดของข้อผิดพลาด

หากต้องการความลึกระดับนั้น ให้รันตัวตรวจสอบแบบ CLI เฉพาะทาง เช่น redocly lint, swagger-cli validate หรือ spectral lint ใช้เครื่องมือนี้สำหรับตรวจความถูกต้องอย่างรวดเร็วก่อนคุณจะ commit หรือแชร์สเปก

เวอร์ชัน OpenAPI ที่ใช้กันจริง

เวอร์ชัน หมายเหตุ
Swagger 2.0 ยังใช้กันแพร่หลาย ใช้ swagger: "2.0"
OpenAPI 3.0.x สาย 3.x ที่พบบ่อยที่สุด
OpenAPI 3.1.0 สอดคล้องกับ JSON Schema 2020-12

ตัวตรวจสอบนี้รับได้ทั้งฟิลด์ openapi (3.x) และฟิลด์ swagger (2.0) ดังนั้นทั้งหมดนี้ผ่านการตรวจเวอร์ชัน

เอกสารขั้นต่ำที่ผ่าน

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

ทุกฟิลด์ที่จำเป็นมีครบ path เดียวขึ้นต้นด้วยสแลช และ get เป็นเมธอดที่รู้จัก ดังนั้นจึงถูกรายงานว่าถูกต้องเชิงโครงสร้าง

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

Swagger คือชื่อเดิมของสเปกนี้ ซึ่งบริจาคให้มูลนิธิ Linux ในปี 2015 และเปลี่ยนชื่อเป็น “OpenAPI” ตั้งแต่เวอร์ชัน 3.0 ปัจจุบัน “Swagger” หมายถึงเครื่องมือ (Swagger UI, Swagger Editor) ส่วนตัวสเปกเองคือ OpenAPI ตัวตรวจสอบนี้รับได้ทั้งฟิลด์เวอร์ชัน swagger (2.0) และ openapi (3.x)

ไม่ใช่ มันตรวจโครงสร้างหลัก คือเอกสาร parse ได้ มีฟิลด์เวอร์ชัน มีออบเจกต์ info ที่มี title และ version และมีออบเจกต์ paths และเตือน path ที่ไม่มีสแลชนำหน้าและเมธอดที่ไม่รู้จัก มันไม่ตรวจทุกโหนดเทียบกับ JSON Schema ทางการ ให้ใช้ redocly lint หรือ spectral lint สำหรับสิ่งนั้น

ไม่ มันไม่ตามการอ้างอิง $ref หรือตรวจว่าคอมโพเนนต์ที่มันชี้ไปมีอยู่จริง สำหรับการอ้างอิงข้ามไฟล์ ให้รวมเอกสารก่อนด้วยเครื่องมืออย่าง redocly bundle หรือ swagger-cli bundle แล้วจึงรันตัวตรวจสอบแบบเต็ม

ไม่ มันตรวจเฉพาะเอกสารที่คุณวางเท่านั้น ไม่ใช่โค้ดที่กำลังรัน มันบอกไม่ได้ว่า API ของคุณคืนค่าตามที่สเปกอธิบายไว้จริงหรือไม่ เครื่องมือทดสอบสัญญา (contract testing) อย่าง Dredd หรือ Schemathesis ทำหน้าที่นั้น

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

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

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

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

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

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

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

ตัวแปลง Timestamp

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

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

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

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

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

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

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