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 ทำหน้าที่นั้น

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

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

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

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

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

ตารางอ้างอิงแป้นพิมพ์ลัด

ค้นหาแป้นพิมพ์ลัดเริ่มต้นตามเอกสารของ VS Code, Chrome และ Bash ที่ใช้ GNU Readline บน macOS, Windows และ Linux

ตัวตรวจสอบอีเมล

ตรวจสอบที่อยู่อีเมล: ตรวจไวยากรณ์ RFC 5322 ค้นหา MX เรกคอร์ดแบบเรียลไทม์ พร้อมรายละเอียดส่วนท้องถิ่น โดเมน และความยาว ไม่มีการส่งอีเมลใด ๆ

เครื่องมือสร้าง EditorConfig

สร้างไฟล์ .editorconfig ด้วยกฎสไตล์และขนาดการเยื้อง การจบบรรทัด ชุดอักขระ และช่องว่างของคุณ เพื่อให้การจัดรูปแบบสอดคล้องกันในทุก IDE และโปรแกรมแก้ไข

ตัวลดรูปพีชคณิตบูลีน

ประเมินนิพจน์บูลีนสำหรับทุกชุดอินพุตและดูตารางค่าความจริงที่สมบูรณ์ รองรับตัวแปรสูงสุดห้าตัวและตัวดำเนินการ &, |, !, ^

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