Softonic

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

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

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

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

  1. 1

    วางเอกสาร

    วางสเปคของคุณในรูปแบบ JSON หรือ YAML แม้จะยังทำไม่เสร็จก็ตาม

  2. 2

    เรียกการตรวจ

    ไปยังขั้นตอนผลลัพธ์ ฟิลด์ที่หายไปแต่ละรายการจะปรากฏเป็นข้อผิดพลาดแยกกัน

  3. 3

    เพิ่มส่วนที่ขาด

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

  4. 4

    ตรวจอีกครั้ง

    วางสเปคที่อัปเดตแล้วเรียกการตรวจอีกครั้ง จนไม่มีข้อผิดพลาดแสดงอีก

ส่วนที่จำเป็นสี่ส่วน

ฟิลด์ อยู่ที่ใด ตัวอย่าง
ฟิลด์ version ระดับบนสุด openapi: 3.0.3 หรือ swagger: "2.0"
info.title ภายใน info title: Orders API
info.version ภายใน info version: 1.0.0
paths ระดับบนสุด paths: ที่มีพาธแรกอย่างน้อยหนึ่งรายการ

ค่า info.version คือเวอร์ชันของ API ของคุณเอง ไม่ใช่เวอร์ชันของสเปค OpenAPI หลายคนมักลืมฟิลด์นี้เพราะเวอร์ชันของสเปคเขียนไว้ที่ด้านบนแล้ว

ตัวอย่างที่ขาดทุกอย่าง

servers:
  - url: https://api.example.com

เอกสารเล็ก ๆ นี้ไม่มีส่วนที่จำเป็นเลยสักส่วน รายงานจะแสดงข้อผิดพลาดสามรายการ

สิ่งที่พบ ชนิด
Missing ‘openapi’ or ‘swagger’ version field. ข้อผิดพลาด
Missing ‘info’ object. ข้อผิดพลาด
Missing ‘paths’ object. ข้อผิดพลาด

เมื่ออ็อบเจกต์ info หายไปทั้งหมด เครื่องมือจะรายงานข้อผิดพลาดนั้นเพียงรายการเดียว และไม่แสดง title กับ version แยกต่างหาก เพิ่ม info พร้อมทั้งสองฟิลด์ การรันครั้งถัดไปจะรายงานหากฟิลด์ใดยังขาดอยู่

โครงเริ่มต้น

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

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

ควรรันการตรวจนี้เมื่อใด

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

เมื่อผ่านฟิลด์ที่จำเป็นแล้ว สิ่งที่ควรเพิ่มต่อไปคือ description สั้น ๆ ใต้ info, รายการ servers และ operationId ของแต่ละการดำเนินการ การตรวจนี้ไม่ได้ตรวจส่วนเหล่านี้ แต่ช่วยให้สเปคอ่านง่ายขึ้นและแปลงเป็นโค้ดไคลเอนต์ได้สะดวกขึ้น

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

ไม่ ฟิลด์ openapi ระบุเวอร์ชันของสเปคที่คุณใช้ ส่วน info.version คือเวอร์ชันของ API ของคุณเอง เช่น 1.0.0

คีย์ต้องมีอยู่และเป็นอ็อบเจกต์ แต่การตรวจนี้ไม่ได้บังคับให้มีพาธอยู่ข้างใน ควรเพิ่มพาธจริงก่อนเผยแพร่

การตรวจ title และ version จะทำงานเฉพาะเมื่อมีอ็อบเจกต์ info เท่านั้น ให้เพิ่ม info แล้วรันใหม่เพื่อดูว่าฟิลด์ของมันครบหรือไม่

ไม่ ที่นี่ต้องการเพียงฟิลด์ version, info, title, version และ paths เท่านั้น รายละเอียดระดับการดำเนินการจะไม่ได้รับการตรวจ

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

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

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

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