เมื่อคุณเปิดเอกสาร API ออนไลน์ที่เผยแพร่โดยใช้ Apidog คุณจะสังเกตเห็นปุ่ม "Try it" ถัดจากแต่ละปลายทาง (endpoint) การคลิกปุ่มนี้จะเลื่อนแผงดีบัก (debug panel) ออกมาทางด้านขวาของหน้า ทำให้คุณสามารถทดสอบ API ได้โดยตรงภายในเอกสาร
อย่างไรก็ตาม ความสามารถในการใช้งานของฟีเจอร์ "Debug" นี้ส่วนใหญ่ขึ้นอยู่กับการที่คุณได้กำหนดค่าไว้อย่างดีเพียงใดภายในแพลตฟอร์ม ปัจจัยต่างๆ เช่น การตั้งค่า URL ที่เหมาะสม, การกำหนดค่าการรับรองความถูกต้อง (authentication), โครงสร้างพารามิเตอร์ที่ชัดเจน และข้อมูลตัวอย่างที่สมบูรณ์ ส่งผลกระทบอย่างมากต่อประสบการณ์การดีบัก
หากไม่ได้กำหนดค่าอย่างถูกต้อง ผู้ใช้อาจใช้เวลามากในการกรอกพารามิเตอร์ หรือแม้แต่ไม่สามารถเรียกใช้ API ได้สำเร็จ ซึ่งห่างไกลจากอุดมคติ
เรามาพูดคุยกันถึงวิธีการกำหนดค่า Apidog อย่างมีประสิทธิภาพ เพื่อให้แน่ใจว่าเอกสารออนไลน์ที่เผยแพร่ให้ประสบการณ์การดีบักที่ยอดเยี่ยม
การกำหนดค่า URL ที่เหมาะสม
บ่อยครั้งที่เอกสารออนไลน์ดูดี แต่กลับล้มเหลวเมื่อคุณคลิกปุ่ม "Try it" เพื่อส่งคำขอ สาเหตุที่พบบ่อยที่สุดคือปลายทาง (endpoint) มีเพียงพาธ (path) เช่น /pet/{petId} โดยไม่ได้เลือกสภาพแวดล้อมการรันไทม์ (runtime environment) ในระหว่างการเผยแพร่
สิ่งนี้ส่งผลให้ URL คำขอไม่สมบูรณ์ โดยไม่มีโปรโตคอลหรือชื่อโฮสต์ ซึ่งนำไปสู่ข้อผิดพลาดเมื่อส่งคำขอ
เพื่อแก้ไขปัญหานี้ ให้แน่ใจว่าผู้ใช้สามารถเข้าถึง URL ที่ถูกต้อง Apidog มีสามวิธีในการกำหนดค่า URL สำหรับเอกสารออนไลน์ ขึ้นอยู่กับความต้องการของคุณ
1. ใช้ Base URL
นี่คือแนวทางที่แนะนำ กำหนดเพียงพาธ (path) ในปลายทาง (endpoint) เช่น /pet/{petId} และกำหนดค่าที่อยู่บริการแบบเต็ม (เช่น https://product.example.com) ในส่วน "การจัดการสภาพแวดล้อม (Environment Management)" เป็น Base URL
เมื่อเผยแพร่เอกสาร API ให้เลือกสภาพแวดล้อมการรันไทม์ (runtime environment) ที่เหมาะสม Apidog จะเชื่อม Base URL กับพาธของปลายทางโดยอัตโนมัติ คุณยังสามารถกำหนดสภาพแวดล้อมการรันไทม์หลายรายการ โดยแต่ละรายการมี Base URL ของตัวเอง
ในเอกสารออนไลน์ ผู้ใช้สามารถสลับสภาพแวดล้อมได้อย่างรวดเร็วจากรายการแบบเลื่อนลง และ URL ของปลายทางทั้งหมดจะอัปเดตตามไปด้วย ทำให้สะดวกในการตรวจสอบ API ในสภาพแวดล้อมที่แตกต่างกัน
หมายเหตุ: โปรดระวังปัญหาโปรโตคอล เบราว์เซอร์หลายตัวจำกัดหน้า HTTPS ไม่ให้เรียกใช้ API แบบ HTTP หาก API ของคุณใช้ HTTP ผู้ใช้อาจพบปัญหาข้ามโปรโตคอลเมื่อดีบักบนหน้าเอกสาร HTTPS
2. รวม Full URL ในปลายทาง
อีกทางเลือกหนึ่งคือการระบุ Full URL โดยตรงในปลายทาง เช่น https://product.example.com/pet/{petId}
สิ่งนี้ทำให้แน่ใจว่า Full URL ของคำขอจะแสดงให้เห็นไม่ว่าจะเลือกสภาพแวดล้อมการรันไทม์ใดก็ตาม อย่างไรก็ตาม การจัดการการเปลี่ยนแปลงที่อยู่เซิร์ฟเวอร์จะกลายเป็นเรื่องยุ่งยาก เนื่องจากคุณจะต้องอัปเดตแต่ละปลายทางทีละรายการ ดังนั้น วิธีนี้จึงไม่ค่อยแนะนำ
3. ใช้ตัวแปรใน URL
หากคุณต้องการให้ผู้ใช้ปรับแต่ง URL สำหรับการดีบัก คุณสามารถใช้ตัวแปรได้ ตัวอย่างเช่น สร้างตัวแปรสภาพแวดล้อม BaseURL ในส่วน "การจัดการสภาพแวดล้อม (Environment Management)" และอ้างอิงใน Base URL เป็น {{BaseURL}}
ในเอกสารออนไลน์ ผู้ใช้สามารถคลิกชื่อตัวแปรและแก้ไขเป็น URL ที่ต้องการได้
หรืออีกทางหนึ่ง คุณสามารถกำหนดตัวแปรโดยตรงในปลายทาง เช่น {{BaseURL}}/pet/{petId}
สำหรับปลายทางเฉพาะนั้นในเอกสารออนไลน์ ผู้ใช้สามารถตั้งค่าตัวแปรเพื่อส่งคำขอได้
ก่อนเผยแพร่เอกสาร ให้แน่ใจว่า "ค่าเริ่มต้น (initial values)" ในสภาพแวดล้อมไม่มีข้อมูลที่ละเอียดอ่อน (เช่น ข้อมูลประจำตัวสำหรับการรับรองความถูกต้อง) เนื่องจากค่าเหล่านี้จะถูกรวมอยู่ในเอกสารที่เผยแพร่และอาจก่อให้เกิดความเสี่ยงด้านความเป็นส่วนตัว
การกำหนดค่าการรับรองความถูกต้อง (Auth) ที่เหมาะสม
การตั้งค่า Basic Auth
การร้องขอปลายทางที่สำเร็จมักต้องมีการรับรองความถูกต้อง (auth) Apidog รองรับประเภทการรับรองความถูกต้องที่หลากหลาย รวมถึง Bearer Token, API Key, OAuth2.0 และ Basic Auth
คุณสามารถกำหนดค่าการรับรองความถูกต้องได้ที่ระดับปลายทาง (endpoint) หรือระดับโฟลเดอร์ โดยใช้ security scheme หรือโดยการตั้งค่าด้วยตนเอง
ตัวอย่างเช่น เมื่อใช้ Bearer Token เป็นประเภทการรับรองความถูกต้อง ช่อง "Token" จะปรากฏที่ด้านบนของแผงดีบักในเอกสารออนไลน์ ผู้ใช้สามารถป้อนค่าโทเค็นได้โดยตรงโดยไม่ต้องเพิ่มคำนำหน้า "Bearer" ด้วยตนเอง Apidog จัดการสิ่งนี้โดยอัตโนมัติ ทำให้สะดวกกว่าการเพิ่มส่วนหัวการอนุญาต (authorization header) ด้วยตนเอง
ข้อดีของการตั้งค่านี้คือข้อมูลการรับรองความถูกต้องสามารถแชร์ข้ามปลายทางหลายรายการได้ หากปลายทางหลายรายการใช้ security scheme หรือประเภทเดียวกัน คุณจะต้องป้อนข้อมูลประจำตัวเพียงครั้งเดียว การอัปเดตข้อมูลประจำตัวใดๆ จะถูกนำไปใช้กับปลายทางที่เกี่ยวข้องทั้งหมดโดยอัตโนมัติ
ข้อมูลประจำตัวสำหรับการรับรองความถูกต้องจะถูกเข้ารหัสและจัดเก็บไว้ในเครื่องในเบราว์เซอร์ของผู้ใช้ จัดการต่อเซสชัน และแชร์ข้ามแท็บและหน้าต่าง ข้อมูลจะถูกล้างเมื่อปิดเบราว์เซอร์ ซึ่งช่วยลดความเสี่ยงในการเปิดเผยข้อมูลที่ละเอียดอ่อนในเอกสารที่เผยแพร่
การกำหนดค่า OAuth2.0
สำหรับการรับรองความถูกต้อง OAuth2.0 หากคุณต้องการให้ผู้ใช้สร้างโทเค็นได้โดยตรงในระหว่างการดีบัก ให้กำหนดค่ารายละเอียดของ Authorization Server (เช่น Auth URL, Token URL) ในโปรเจกต์
เมื่อใช้ security scheme ของ OAuth2.0 ผู้ใช้จะต้องป้อน client ID, client secret ฯลฯ ในระหว่างการดีบัก หน้าต่างป๊อปอัปจะแนะนำขั้นตอนการอนุญาต และ access_token ที่ได้รับจะถูกนำไปใช้กับการร้องขอ API ถัดไปโดยอัตโนมัติ
ออกแบบโครงสร้างพารามิเตอร์ที่ชัดเจน
การแสดงพารามิเตอร์ในแผงดีบัก
แผงดีบักจะแสดงส่วนพารามิเตอร์อย่างชาญฉลาดตามการออกแบบปลายทางของคุณ ตัวอย่างเช่น หากปลายทางกำหนดเพียงพารามิเตอร์ Path แผงดีบักจะแสดงเฉพาะส่วน Path เท่านั้น หลีกเลี่ยงส่วน Query หรือ Body ที่ไม่จำเป็น
ความชัดเจนนี้ช่วยให้ผู้ใช้เข้าใจว่าต้องกรอกพารามิเตอร์ใดบ้าง โดยไม่ถูกรบกวนจากส่วนที่ไม่เกี่ยวข้อง
ระบุตัวอย่าง
เมื่อออกแบบปลายทาง ให้กำหนดประเภทและคุณสมบัติที่จำเป็นของแต่ละพารามิเตอร์อย่างถูกต้อง ใส่คำอธิบายและตัวอย่างที่ชัดเจน เนื่องจากสิ่งเหล่านี้จะถูกเติมไว้ล่วงหน้าในแผงดีบัก ซึ่งช่วยปรับปรุงความสามารถในการใช้งาน
หลีกเลี่ยงส่วนหัวที่ซ้ำซ้อน
หากปลายทางกำหนดพารามิเตอร์ Body ไม่จำเป็นต้องเพิ่มส่วนหัวด้วยตนเอง เช่น Content-Type: application/json Apidog จัดการส่วนหัวดังกล่าวโดยอัตโนมัติระหว่างการร้องขอ
ในทำนองเดียวกัน หากมีการกำหนดค่าการรับรองความถูกต้อง ให้หลีกเลี่ยงการทำซ้ำในส่วนหัว การตั้งค่าการรับรองความถูกต้องมีความสำคัญเหนือกว่าและจะแทนที่การกำหนดค่าส่วนหัวที่ขัดแย้งกัน
เสนอตัวอย่างคำขอที่ครอบคลุม
สำหรับปลายทางที่มีเนื้อหาคำขอ JSON ที่ซับซ้อน ให้ระบุ ตัวอย่างเนื้อหาคำขอหลายรายการ ในระหว่างการออกแบบ
ผู้ใช้สามารถเลือกตัวอย่างเหล่านี้จากเมนูแบบเลื่อนลงในแผงดีบัก ซึ่งช่วยประหยัดเวลาและลดข้อผิดพลาด
ตรวจสอบให้แน่ใจว่าข้อมูลตัวอย่างมีความคล้ายคลึงกับสถานการณ์จริง แต่หลีกเลี่ยงการรวมข้อมูลที่ละเอียดอ่อน ผู้ใช้สามารถแก้ไขตัวอย่างเหล่านี้ได้ตามต้องการ
กำหนดค่าตัวอย่างการตอบกลับที่ชัดเจน
หลังจากส่งคำขอ แผงดีบักจะแสดงการตอบกลับทั้งหมด รวมถึงรหัสสถานะ ส่วนหัว และเนื้อหา ในฐานะผู้สร้างเอกสาร ให้กำหนดค่าตัวอย่างการตอบกลับที่ชัดเจนเพื่อช่วยให้ผู้ใช้เข้าใจผลลัพธ์ที่เป็นไปได้
ระบุตัวอย่างการตอบกลับหลายรายการสำหรับแต่ละปลายทาง เช่น สำเร็จ (200), คำขอไม่ถูกต้อง (400) และไม่ได้รับอนุญาต (401)
ให้ความสนใจเป็นพิเศษกับการตอบกลับข้อผิดพลาด โดยอธิบายรหัสข้อผิดพลาดและรูปแบบข้อความสำหรับสถานการณ์ต่างๆ อย่างชัดเจน สิ่งนี้ช่วยให้ผู้ใช้ระบุและแก้ไขปัญหาได้อย่างรวดเร็วในระหว่างการดีบัก
ระบุโค้ดตัวอย่างสำหรับการรวมระบบ
แม้ว่า Apidog จะสร้างโค้ดตัวอย่างสำหรับภาษาโปรแกรมทั่วไปโดยอัตโนมัติ แต่โค้ดที่สร้างขึ้นอาจไม่สอดคล้องกับความต้องการทางธุรกิจของคุณอย่างสมบูรณ์ ในกรณีเช่นนี้ ให้ปรับแต่งตัวอย่าง
คุณสามารถกำหนดค่าภาษาที่ต้องการตัวอย่างที่สร้างขึ้นโดยอัตโนมัติได้ใน "Project Settings -> Endpoint Feature Settings -> Request Code Samples"
นอกจากนี้ คุณยังสามารถเขียนโค้ดตัวอย่างที่กำหนดเองสำหรับปลายทางเฉพาะในส่วน "Endpoint Description" ได้อีกด้วย
สิ่งนี้ช่วยให้แน่ใจว่าผู้ใช้จะเห็นทั้งตัวอย่างที่สร้างขึ้นโดยอัตโนมัติและตัวอย่างที่กำหนดเองในเอกสารออนไลน์ ทำให้การรวมระบบง่ายขึ้น
สรุป
ประสบการณ์การดีบักของเอกสารออนไลน์ขึ้นอยู่กับการกำหนดค่าที่เหมาะสมอย่างมาก ด้วยการตั้งค่า URL, การรับรองความถูกต้อง, โครงสร้างพารามิเตอร์ และตัวอย่างอย่างรอบคอบ คุณสามารถมั่นใจได้ว่าผู้ใช้จะเริ่มต้นใช้งาน API ของคุณได้อย่างรวดเร็ว โดยไม่ติดขัดกับรายละเอียดทางเทคนิค