Swagger คืออะไรและใช้อย่างไร

Swagger เป็นเครื่องมือพิเศษที่สร้างเอกสาร RESTful API ของแอปพลิเคชันของคุณโดยอัตโนมัติ

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

ในการเข้าถึง Swagger คุณจะต้องกดปุ่ม Preview ในแอปพลิเคชันที่เผยแพร่แล้วคลิกชื่อของแผนการเผยแพร่ที่ต้องการ ( แผนการ Deploy Plan )

ในหน้าต่างที่เพิ่งเปิดใหม่ จะแสดงรายการของจุดสิ้นสุดและวิธีการที่เกี่ยวข้องกับจุดสิ้นสุดเหล่านี้ คำขอบางรายการมีให้สำหรับผู้ใช้ที่ได้รับอนุญาตบางกลุ่มเท่านั้น (ดู Middleware ของ Auth module สำหรับคำขอเฉพาะแต่ละรายการในส่วน Endpoints ) จำเป็นต้องมี Bearer Token สำหรับคำขอที่อนุญาตสำหรับผู้ใช้ที่ได้รับอนุญาตเท่านั้น

คุณสามารถเข้าถึงปลายทางที่เกี่ยวข้องได้โดยตรงใน Swagger เพื่อรับโทเค็นนี้ (ส่วนการตรวจสอบสิทธิ์, POST /auth Auth ถูกต้อง)

กด Try it out ป้อนชื่อผู้ใช้และรหัสผ่านเพื่อรับโทเค็น

คำขอจะถูกส่งเมื่อ Execute หากดำเนินการสำเร็จ คุณจะเห็นฟิลด์ token ที่มีค่า Bearer token

วิธีที่สองในการรับโทเค็นผู้ใช้ที่ได้รับอนุญาตคือโทเค็นสามารถพบได้ในเนื้อหาคำขอของแอปพลิเคชันที่ปรับใช้

1. กด F12 ในเว็บเบราว์เซอร์ของคุณเพื่อเปิดเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์
2. ส่งคำขอใดๆ ในแอปพลิเคชันที่ปรับใช้ของคุณ (เช่น อัปเดตตาราง เป็นต้น) ผู้ใช้ที่ส่งคำขอนี้ต้องได้รับอนุญาตให้เข้าถึงปลายทางนี้
3. เปิดแท็บ Network และค้นหาคำขอที่เกี่ยวข้อง
4. ไปที่แท็บ Headers และค้นหา Request Headers Bearer token จะแสดงภายใต้ Authorization

ระบุ Bearer token ให้กับ Swagger โดยกด Authorize และวางค่าที่คุณคัดลอกในขั้นตอนก่อนหน้า

สำหรับคำขอทดสอบ ให้เลือกกลุ่มที่ต้องการและวิธีการที่คุณต้องการดำเนินการ กด Try it out กรอกพารามิเตอร์การป้อนคำขอ คลิก Execute เพื่อดำเนินการตอบกลับ

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

• 401 - คำขอไม่เสร็จสมบูรณ์เนื่องจากโทเค็นการอนุญาตที่จำเป็นขาดหายไปหรือไม่ถูกต้อง

• 404 - คำขอได้รับการประมวลผลสำเร็จ แต่ไม่พบทรัพยากรที่ร้องขอ

• 422 - พารามิเตอร์ที่ไม่ถูกต้องถูกส่งไปยังอินพุตของคำขอ

• 500 - ข้อผิดพลาดในการประมวลผลคำขอโดยเซิร์ฟเวอร์

เพิ่มข้อผิดพลาดที่กำหนดเอง

สำหรับ BP แบบกำหนดเองและคำขอที่เกี่ยวข้อง คุณสามารถสร้างรหัสข้อผิดพลาดแบบกำหนดเองพร้อมคำอธิบายโดยใช้บล็อก Raise Error ในโปรแกรมแก้ไข BP ตัวอย่างของกระบวนการดังกล่าวอยู่ด้านล่าง:

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

หมายเหตุ: รหัสตอบกลับข้อผิดพลาดไคลเอนต์ HTTP 418 I'm a teapot ระบุว่าเซิร์ฟเวอร์ปฏิเสธที่จะชงกาแฟเพราะเป็นกาน้ำชาอย่างถาวร หม้อต้มกาแฟ/ชาแบบผสมที่กาแฟหมดชั่วคราวควรส่งคืน 503 แทน ข้อผิดพลาดนี้อ้างอิงถึง Hyper Text Coffee Pot Control Protocol ที่กำหนดไว้ในเรื่องตลกของ April Fools ในปี 1998 และ 2014