ตัวตรวจสอบ Swagger 2.0

อะไรนับว่าผ่านการตรวจของ Swagger 2.0

สำหรับไฟล์ 2.0 การตรวจเวอร์ชันจะผ่านเมื่อมีคีย์ swagger อยู่ที่ระดับบนสุด เครื่องมือไม่ได้ตรวจว่าค่านั้นเป็น "2.0" หรือไม่ ดังนั้นจะไม่พบเลขเวอร์ชันที่ผิด นอกจากเวอร์ชันแล้ว ไฟล์ยังต้องมี info.title, info.version และอ็อบเจกต์ paths

ฟิลด์ที่เฉพาะกับ Swagger 2.0 เช่น host, basePath, schemes, definitions และ securityDefinitions จะไม่ได้รับการตรวจ หากไม่มี host หรือบล็อก definitions เสียหาย จะไม่มีการรายงาน

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

{
  "swagger": "2.0",
  "info": { "title": "Shop API", "version": "1.0" },
  "paths": {
    "/products": {
      "get": { "summary": "List products" },
      "x-internal": true
    }
  }
}

มีฟิลด์เวอร์ชัน info และ paths ครบ จึงไม่มีข้อผิดพลาด รายงานแสดงคำเตือนหนึ่งรายการ

คำเตือนไม่ทำให้เอกสารไม่ถูกต้อง เอกสารนี้จึงยังถูกรายงานว่าถูกต้อง คีย์ส่วนขยายของผู้จำหน่ายอย่าง x-internal เป็นสิ่งที่ถูกต้องตามกฎใน Swagger 2.0 คุณจึงคงไว้ได้

การย้ายจาก 2.0

หากคุณวางแผนย้ายไปยัง OpenAPI 3.x คุณสามารถวางไฟล์ที่แปลงแล้วในช่องเดิมและเปรียบเทียบผลลัพธ์ได้ การตรวจเหมือนเดิม เพียงเปลี่ยนฟิลด์ swagger เป็น openapi สำหรับงานย้ายจริง ให้ใช้ตัวแปลงและลินเตอร์ฉบับเต็ม เพราะเครื่องมือนี้ไม่ได้แปลงการตั้งค่า definitions หรือ host

เมื่อการตรวจอย่างรวดเร็วก็เพียงพอ

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

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