วิธีเพิ่มตัวอย่าง Body ของ Request หลายรายการด้วย Apidog

Apidog รองรับการเพิ่มตัวอย่าง request body หลายรายการ สำหรับแต่ละ endpoint ทำให้เอกสาร API ของคุณมีประโยชน์และเข้ากันได้กับข้อมูลจำเพาะของ OpenAPI มากขึ้น คุณสมบัตินี้ช่วยให้คุณแสดงวิธีการสร้าง request ที่แตกต่างกันสำหรับ endpoint เดียวกัน ซึ่งช่วยให้นักพัฒนาเข้าใจวิธีการใช้ API ของคุณในสถานการณ์ต่างๆ

ตัวอย่าง request body มีประโยชน์เนื่องจาก:

แสดงให้นักพัฒนาเห็นวิธีการจัดรูปแบบ request ของพวกเขาอย่างแม่นยำ
สาธิตกรณีการใช้งานที่แตกต่างกันสำหรับ endpoint เดียวกัน
ทำให้การทดสอบง่ายขึ้นโดยการจัดเตรียมโครงสร้าง request ที่พร้อมใช้งาน
ตรวจสอบให้แน่ใจว่าเอกสารของคุณเป็นไปตามมาตรฐาน OpenAPI

คุณสามารถเพิ่มได้มากเท่าที่คุณต้องการเพื่อให้ครอบคลุมทุกสถานการณ์ที่เป็นไปได้

ขั้นตอนต่อขั้นตอน: การเพิ่มตัวอย่าง Request Body แรกของคุณ

การเพิ่มตัวอย่าง request body ใน Apidog นั้นง่ายมาก นี่คือวิธีการเริ่มต้น:

1. เปิดโปรเจกต์ API ของคุณ ใน Apidog (เวอร์ชัน 2.7.0 หรือสูงกว่า)

2. ไปที่ endpoint ที่คุณต้องการเพิ่มตัวอย่าง

3. คลิกแท็บ "แก้ไข" เพื่อเข้าถึงตัวแก้ไขเอกสารและ เลื่อนไปที่ส่วน "Request Body"

4. คลิกที่ "เพิ่มตัวอย่าง" เพื่อสร้างตัวอย่างใหม่

5. กรอกรายละเอียดตัวอย่าง:

ชื่อตัวอย่าง: ตั้งชื่อตัวอย่างของคุณให้ชัดเจน (เช่น "Standard Request")
ค่าตัวอย่าง: ป้อนข้อมูล JSON, XML หรือข้อมูลรูปแบบอื่นๆ จริง
คำอธิบาย: อธิบายเมื่อใช้ตัวอย่างนี้ (รองรับ Markdown)
OAS Key: ระบุตัวระบุสำหรับการส่งออก OpenAPI (ไม่บังคับแต่แนะนำ)
OAS Extensions: เพิ่มฟิลด์ที่กำหนดเองที่จำเป็นสำหรับการส่งออก (ไม่บังคับ)

6. คลิก "บันทึก" เพื่อสร้างตัวอย่าง

ชื่อตัวอย่างช่วยให้ผู้ใช้ระบุวัตถุประสงค์ของแต่ละตัวอย่าง หากคุณปล่อยว่างไว้ Apidog จะตั้งชื่อให้โดยอัตโนมัติว่า "ตัวอย่าง 1", "ตัวอย่าง 2" เป็นต้น

ค่าตัวอย่างควรแสดงโครงสร้าง request ที่ถูกต้อง สำหรับประเภทเนื้อหา JSON Apidog มีตัวแก้ไขที่มีโครงสร้างเพื่อช่วยให้มั่นใจได้ถึงการจัดรูปแบบที่ถูกต้อง

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

OAS Key มีความสำคัญหากคุณวางแผนที่จะส่งออกเอกสารของคุณไปยังรูปแบบ OpenAPI คีย์นี้จะกลายเป็นตัวระบุสำหรับตัวอย่างในข้อมูลจำเพาะที่ส่งออก

การสร้างตัวอย่างหลายรายการสำหรับสถานการณ์ต่างๆ

หลังจากเพิ่มตัวอย่างแรกของคุณแล้ว คุณจะต้องสร้างตัวอย่างเพิ่มเติมสำหรับกรณีการใช้งานที่แตกต่างกัน:

คลิกปุ่ม "+ เพิ่ม" อีกครั้ง เพื่อสร้างตัวอย่างอื่น
ตั้งชื่อที่แตกต่างกัน ซึ่งระบุสถานการณ์ได้อย่างชัดเจน (เช่น "Minimal Request")
ป้อนค่าตัวอย่าง สำหรับสถานการณ์เฉพาะนี้
เพิ่มคำอธิบายโดยละเอียด อธิบายเมื่อใช้ตัวอย่างนี้
กำหนดค่า OAS Key และ Extensions ตามต้องการ
คลิก "บันทึก" เพื่อเพิ่มตัวอย่าง
ทำซ้ำขั้นตอนนี้ สำหรับสถานการณ์ที่เกี่ยวข้องทั้งหมด

adding another request body example in the endpoint documentation

เมื่อสร้างตัวอย่างหลายรายการ ให้พิจารณาครอบคลุมสถานการณ์ทั่วไปเหล่านี้:

Standard Request: วิธีทั่วไปในการใช้ endpoint
Minimal Request: โครงสร้าง request ที่ถูกต้องที่ง่ายที่สุด
Complete Request: request ที่ใช้ฟิลด์ที่เป็นไปได้ทั้งหมด
Special Case: ตัวอย่างสำหรับสถานการณ์ทางธุรกิจที่ไม่เหมือนใคร

แต่ละตัวอย่างควรแสดงวิธีการใช้ endpoint ที่แตกต่างกัน สิ่งนี้ช่วยให้นักพัฒนาเข้าใจถึงความเป็นไปได้ทั้งหมดเมื่อทำงานกับ API ของคุณ

Apidog แสดงตัวอย่างตามลำดับเฉพาะ:

ตัวอย่างที่มีชื่อมาก่อนตัวอย่างที่ไม่มีชื่อ
ตัวอย่างที่มี OAS Keys จะแสดงก่อนตัวอย่างที่ไม่มี
ตัวอย่างที่ไม่มีชื่อหรือ OAS Keys จะถูกจัดเรียงตามหมายเลขซีเรียล

documenting request body examples using Apidog

เพื่อให้ตัวอย่างที่สำคัญที่สุดของคุณปรากฏก่อน ให้ตั้งชื่อและ OAS Keys ให้ชัดเจน

การใช้ตัวอย่าง Request Body สำหรับการทดสอบ

หนึ่งในคุณสมบัติที่ดีที่สุดของตัวอย่าง request body หลายรายการคือวิธีที่ช่วยลดความซับซ้อนในการทดสอบ:

ไปที่หน้า "Run" ของ endpoint ของคุณ
ค้นหาส่วน "สร้างอัตโนมัติ" ในการกำหนดค่า request
คลิกเมนูแบบเลื่อนลง เพื่อดูตัวอย่างที่มีทั้งหมด
เลือกตัวอย่าง ที่คุณต้องการทดสอบ
request body จะถูกเติมโดยอัตโนมัติ ด้วยตัวอย่างที่เลือก
คลิก "ส่ง" เพื่อทดสอบ endpoint ด้วยตัวอย่างนี้

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

Apidog ยังช่วยให้คุณสร้างตัวอย่างจากเซสชันการทดสอบของคุณได้:

กำหนดค่า request body ในหน้า "Run"
คลิกปุ่ม "แยก"
เลือก "แยกไปยังตัวอย่าง Request"
เลือกที่จะสร้างตัวอย่างใหม่หรืออัปเดตตัวอย่างที่มีอยู่
request body ปัจจุบันของคุณจะถูกบันทึกเป็นตัวอย่าง

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

การตรวจสอบให้แน่ใจว่าเข้ากันได้กับ OpenAPI ด้วยตัวอย่างของคุณ

ตัวอย่าง request body ของ Apidog ได้รับการออกแบบมาให้ทำงานได้อย่างราบรื่นกับข้อมูลจำเพาะของ OpenAPI เมื่อคุณส่งออกเอกสาร API ของคุณ ตัวอย่างทั้งหมดของคุณจะถูกจัดรูปแบบอย่างถูกต้องตามมาตรฐาน OAS 3.0/3.1

นี่คือวิธีการจัดการตัวอย่างในระหว่างการส่งออก:

แต่ละตัวอย่างจะรวมอยู่ด้วย ในข้อมูลจำเพาะที่ส่งออก
ชื่อตัวอย่างมาจาก OAS Key หากมีให้ (หรือหมายเลขซีเรียลหากไม่มี)
คำอธิบายตัวอย่างจะถูกเก็บรักษาไว้ ในรูปแบบที่ส่งออก
OAS Extensions ที่กำหนดเองใดๆ จะรวมอยู่ด้วย ในการส่งออก

ข้อมูลจำเพาะ OpenAPI ที่ส่งออกจะรวมตัวอย่างของคุณในโครงสร้างเช่นนี้:

"examples": {
  "standard_request": {
    "value": {
      "name": "John Doe",
      "id": "12345",
      "email": "john.doe@example.com"
    },
    "summary": "Standard Request",
    "description": "This is a standard request with all required fields."
  },
  "minimal_request": {
    "value": {
      "id": "12345"
    },
    "summary": "Minimal Request",
    "description": "This is a minimal request with only the required ID field."
  }
}

เพื่อให้แน่ใจว่าเข้ากันได้ดีที่สุดกับ OpenAPI:

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

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

แนวทางปฏิบัติที่ดีที่สุดสำหรับตัวอย่าง Request Body

เพื่อให้ได้รับประโยชน์สูงสุดจากตัวอย่าง request body หลายรายการ ให้ปฏิบัติตามแนวทางปฏิบัติที่ดีที่สุดเหล่านี้:

สร้างชุดตัวอย่างที่ครอบคลุม

รวมตัวอย่างที่ครอบคลุม:

การใช้งานพื้นฐาน ที่มีเฉพาะฟิลด์ที่จำเป็น
การใช้งานทั่วไป ที่มีฟิลด์เสริมที่ใช้กันทั่วไป
การใช้งานที่สมบูรณ์ แสดงฟิลด์ที่เป็นไปได้ทั้งหมด
Edge cases ที่แสดงสถานการณ์พิเศษ

ใช้การตั้งชื่อที่ชัดเจน

ตั้งชื่อแต่ละตัวอย่างให้ชัดเจนซึ่งระบุวัตถุประสงค์
ใช้รูปแบบการตั้งชื่อที่สอดคล้องกันใน endpoint ที่แตกต่างกัน
หลีกเลี่ยงชื่อทั่วไปเช่น "ตัวอย่าง 1" ที่ไม่ได้อธิบายเนื้อหา

เขียนคำอธิบายที่เป็นประโยชน์

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

จัดระเบียบตัวอย่างอย่างมีตรรกะ

ใส่สถานการณ์ทั่วไปที่สุดไว้ก่อน
จัดกลุ่มตัวอย่างที่เกี่ยวข้องเข้าด้วยกัน
ลบตัวอย่างที่ล้าสมัยเพื่อหลีกเลี่ยงความสับสน
อัปเดตตัวอย่างเมื่อ API ของคุณเปลี่ยนแปลง

ใช้ OAS Keys อย่างมีประสิทธิภาพ

เลือกคีย์ที่มีความหมายซึ่งอธิบายวัตถุประสงค์ของตัวอย่าง
ใช้การตั้งชื่อคีย์ที่สอดคล้องกันใน API ของคุณ
หลีกเลี่ยงอักขระพิเศษที่อาจทำให้เกิดปัญหาในการส่งออก

ด้วยการปฏิบัติตามแนวทางปฏิบัติเหล่านี้ คุณจะสร้างตัวอย่าง request body ที่ช่วยให้นักพัฒนาเข้าใจและใช้ API ของคุณได้อย่างมีประสิทธิภาพอย่างแท้จริง

บทสรุป

การเพิ่มตัวอย่าง request body หลายรายการใน Apidog เป็นวิธีง่ายๆ แต่มีประสิทธิภาพในการปรับปรุงเอกสาร API ของคุณ ด้วยการแสดงวิธีการสร้าง request ที่แตกต่างกันสำหรับ endpoint เดียวกัน คุณช่วยให้นักพัฒนาเข้าใจวิธีการใช้ API ของคุณในสถานการณ์ต่างๆ

ขั้นตอนต่อขั้นตอนนั้นง่ายมาก:

ไปที่ endpoint ของคุณแล้วคลิก "แก้ไข"
เลื่อนไปที่ส่วน Request Body แล้วคลิก "+ เพิ่ม"
กำหนดค่าตัวอย่างของคุณด้วยชื่อ ค่า คำอธิบาย และ OAS Key
ทำซ้ำสำหรับสถานการณ์เพิ่มเติม
ใช้ตัวอย่างของคุณสำหรับการทดสอบและเอกสาร

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

เริ่มเพิ่มตัวอย่าง request body หลายรายการลงในเอกสาร Apidog ของคุณวันนี้เพื่อดูประโยชน์สำหรับตัวคุณเองและผู้ใช้ API ของคุณ

button