ด้วย ปลั๊กอิน IDEA ของ Apidog หรือปลั๊กอิน Swagger บางตัว คุณสามารถสร้างเอกสาร API จากโค้ดได้อย่างง่ายดาย แก้ปัญหาการเขียนเอกสารตั้งแต่เริ่มต้น
อย่างไรก็ตาม แม้หลังจากเขียนเอนด์พอยต์และสร้างเอกสารแล้ว คุณก็อาจยังรู้สึกไม่แน่ใจ: การออกแบบ API ดีพอหรือไม่? เอกสารเป็นมาตรฐานหรือไม่? มีส่วนไหนที่สามารถปรับปรุงให้ดียิ่งขึ้นได้อีก?
โดยเฉพาะในการทำงานร่วมกันเป็นทีม คุณต้องการให้เอกสาร API ของคุณเข้าใจง่ายสำหรับเพื่อนร่วมทีม การตั้งชื่อที่ชัดเจนและความสมบูรณ์ของข้อมูลส่งผลโดยตรงต่อประสบการณ์การใช้ API ของคุณ
Apidog ได้เปิดตัวฟีเจอร์ AI หลายอย่างเมื่อเร็วๆ นี้ เพื่อช่วยคุณปรับปรุงเอกสาร API ให้ดียิ่งขึ้นในขั้นตอนนี้ ไม่ว่าคุณจะกำลังปรับปรุงรายละเอียดเอนด์พอยต์ที่มีอยู่ หรือนำเข้าเอกสาร API ที่มีอยู่จากที่อื่น AI ก็สามารถให้คำแนะนำที่เป็นประโยชน์ได้
ด้านล่างนี้ เราจะแนะนำวิธีการใช้ AI ใน Apidog เพื่อสร้างเอกสาร API ที่เป็นมาตรฐานมากขึ้น ก่อนที่เราจะเริ่มต้น โปรดตรวจสอบให้แน่ใจว่าคุณได้ อัปเดต Apidog เป็นเวอร์ชันล่าสุด, เปิดใช้งานคุณสมบัติ AI และกำหนดค่าโมเดล AI แล้ว
การนำเข้าจากเอกสารที่มีอยู่
บางครั้งคุณจำเป็นต้องย้ายเอกสาร API จากแหล่งอื่นมายัง Apidog หากเอกสารอยู่ในรูปแบบมาตรฐาน Apidog รองรับวิธีการนำเข้าหลายแบบ: คุณสามารถสร้างเอกสารจากโค้ดผ่าน ปลั๊กอิน IDEA, นำเข้าข้อมูลจำเพาะ OpenAPI/Swagger หรือย้ายจากเครื่องมืออื่น ๆ เช่น Postman
แต่ในบางกรณี เอกสารของคุณอาจไม่ได้อยู่ในรูปแบบมาตรฐานเหล่านี้ ตัวอย่างเช่น ทีมงานเคยบันทึกเอนด์พอยต์ใน Markdown, จัดเรียงคำอธิบายฟิลด์ใน Word หรือพบการกำหนดเอนด์พอยต์ในบันทึกการแชทหรืออีเมล การป้อนข้อมูลแต่ละฟิลด์ด้วยตนเองจากแหล่งที่ไม่เป็นมาตรฐานเหล่านี้ลงใน Apidog อาจเป็นเรื่องที่น่าเบื่อหน่าย
ในสถานการณ์นี้ คุณสามารถใช้คุณสมบัติ ปรับเปลี่ยน schema ด้วย AI เพื่อช่วยในการป้อนข้อมูล สมมติว่าคุณมีเนื้อหา Markdown ดังนี้:
| name | desc | type | required |
| ---------- | --------------------------------------------------------------------------- | --------- | -------- |
| usePaging | Whether to enable pagination | boolean | true |
| offset | Starting position (required when pagination is enabled) | int | false |
| pageSize | Number of items per page (required when pagination is enabled) | int | false |
| minPrice | Minimum price (unit: cents) | int | false |
| maxPrice | Maximum price (unit: cents) | int | false |
| brand | Brand code | string | false |
| categoryId | Product category ID | int | false |
| sortRule | Sorting rule: 1 → Sales priority, 2 → Price ascending, 3 → Price descending | enum(int) | false |
| keyword | Search keyword (fuzzy match on product name) | string | false |เพียงแค่คัดลอกพารามิเตอร์แล้วถาม AI ว่า: "แปลงเนื้อหานี้ให้เป็นพารามิเตอร์ของเอนด์พอยต์ โดยต้องระบุประเภทและฟิลด์ที่จำเป็นด้วย"
AI จะตรวจจับชื่อฟิลด์, ประเภทข้อมูล, สถานะที่จำเป็น และคำอธิบายโดยอัตโนมัติ จากนั้นจะแปลงทุกอย่างให้เป็นรูปแบบ schema มาตรฐานของ Apidog หากมีการรวม enum เข้ามา AI ก็จะจัดเรียงให้เป็นประเภท enum ที่เหมาะสมสำหรับคุณด้วย
AI ช่วยให้คุณปรับปรุงรายละเอียด API
หลังจากนำเข้าข้อมูลพื้นฐานแล้ว ขั้นตอนต่อไปคือการปรับปรุงรายละเอียด
หากคุณไม่แน่ใจเกี่ยวกับชื่อฟิลด์ ให้ใช้คุณสมบัติ การตั้งชื่อด้วย AI AI จะให้คำแนะนำการตั้งชื่อที่แม่นยำยิ่งขึ้นตามข้อกำหนดของเอนด์พอยต์และ แนวทางการออกแบบ API
คุณยังสามารถใช้ AI เพื่อเติมเต็มคำอธิบายฟิลด์โดยอัตโนมัติ เพื่อให้คำอธิบายที่ชัดเจนและสมบูรณ์ยิ่งขึ้น
การสร้างข้อมูลจำลองเป็นอีกหนึ่งจุดแข็งของ AI บ่อยครั้งที่เราทราบว่าฟิลด์หมายถึงอะไร แต่ไม่แน่ใจว่าจะใช้ค่าตัวอย่างอะไร AI จะสร้างข้อมูลตัวอย่างที่สมเหตุสมผลโดยอัตโนมัติตามประเภทและคำอธิบายของฟิลด์
การตรวจสอบความสมบูรณ์ของเอกสาร API: หลีกเลี่ยงการละเว้น
เมื่อเอกสารดูเหมือนจะสมบูรณ์เกือบทั้งหมด คุณอาจยังสงสัยว่ามีข้อมูลสำคัญใดขาดหายไปหรือไม่ ณ จุดนี้ ให้ใช้ การตรวจสอบความสมบูรณ์ของเอกสาร API ของ Apidog เพื่อดูว่ามีสิ่งใดถูกมองข้ามไปบ้าง
AI จะสแกนเอกสาร API ที่มีอยู่ของคุณจากหลากหลายมุมมองเพื่อระบุข้อมูลที่ขาดหายไปหรือไม่สมบูรณ์ จากนั้นจะสร้างรายงานโดยละเอียดที่ให้คะแนนแต่ละรายการที่ตรวจสอบ ช่วยให้คุณเห็นได้อย่างรวดเร็วว่าเอกสาร API ของคุณจำเป็นต้องปรับปรุงส่วนใดบ้าง
รายงานไม่เพียงแค่บอกคุณว่าต้องทำอะไร แต่ยังอธิบายถึงเหตุผลด้วย ตัวอย่างเช่น คุณอาจได้บันทึกรูปแบบการตอบสนองที่สำเร็จแล้ว แต่ยังไม่ได้บันทึกสถานการณ์ข้อผิดพลาดที่เป็นไปได้ คุณอาจมีคำอธิบายฟิลด์พื้นฐาน แต่ขาดข้อจำกัดการใช้งานหรือข้อกำหนดการจัดรูปแบบ
คุณสามารถปรับปรุงเอกสาร API ของคุณได้โดยทำตามคำแนะนำที่ให้ไว้ในรายงาน
การตรวจสอบการปฏิบัติตามข้อกำหนดของเอนด์พอยต์: เพื่อความสอดคล้อง
นอกเหนือจากความสมบูรณ์แล้ว เอกสาร API ยังต้องมีมาตรฐานที่ดีอีกด้วย ภายในเอนด์พอยต์เดียว การตั้งชื่อควรเป็นไปตามสไตล์ที่สอดคล้องกัน ประเภทฟิลด์ต้องถูกกำหนดอย่างชัดเจนและถูกต้อง และโครงสร้างการตอบสนองควรมีเหตุผล รายละเอียดเหล่านี้มีบทบาทสำคัญในการทำให้เอกสารของคุณอ่านและดูแลรักษาง่าย
คุณสมบัติ การตรวจสอบการปฏิบัติตามข้อกำหนดของเอนด์พอยต์ ของ Apidog จะตรวจสอบเอกสารของคุณจากหลายมุมมอง ตัวอย่างเช่น หากบางฟิลด์ใช้คำกริยาในการตั้งชื่อ ในขณะที่บางฟิลด์ใช้คำนาม AI จะแจ้งความไม่สอดคล้องกันและแนะนำสไตล์การตั้งชื่อที่เป็นหนึ่งเดียว
นอกจากนี้ยังตรวจสอบว่าคำจำกัดความของฟิลด์เป็นไปตามมาตรฐานที่สอดคล้องกันหรือไม่ เช่น การหลีกเลี่ยงรูปแบบตัวอักษรผสมกัน การใช้เครื่องหมายขีดล่างและ camelCase พร้อมกัน หรือการย่อที่ไม่สอดคล้องกัน จากนั้นจะให้คำแนะนำที่ชัดเจนเกี่ยวกับวิธีการแก้ไขปัญหาเหล่านี้
สรุป
การสร้างเอกสาร API ที่ชัดเจนและเป็นมาตรฐานเป็นสิ่งสำคัญ คุณสมบัติต่างๆ เช่น กรณีทดสอบที่สร้างโดย AI ขึ้นอยู่กับคุณภาพของเอกสารของคุณ ยิ่งเอกสารสมบูรณ์และสอดคล้องกันมากเท่าไหร่ กรณีทดสอบที่สร้างขึ้นก็จะยิ่งแม่นยำและมีประโยชน์มากขึ้นเท่านั้น
คุณไม่จำเป็นต้องใช้ฟีเจอร์ AI ทุกอย่างพร้อมกัน หรือปรับปรุงขั้นตอนการทำงานปัจจุบันของคุณทั้งหมด
นี่เป็นกระบวนการทีละขั้นตอน คุณสามารถเริ่มต้นด้วยการนำเข้าเอกสารที่มีอยู่ของคุณ จากนั้นจึงค่อยๆ ใช้ฟีเจอร์ AI เพื่อปรับปรุงและปรับแต่ง หากคุณไม่แน่ใจเกี่ยวกับข้อเสนอแนะใดๆ คุณสามารถปล่อยไว้ตามเดิมและกลับมาดูใหม่ในภายหลังเมื่อคุณมีบริบทมากขึ้น
เมื่อเวลาผ่านไป คุณจะเข้าใจมาตรฐานเอกสาร API ได้ดีขึ้นโดยธรรมชาติ AI ไม่ได้ช่วยแค่แก้ไขปัญหาเฉพาะหน้าเท่านั้น แต่ยังช่วยให้คุณพัฒนานิสัยการทำเอกสารที่ดีขึ้นด้วย