ASP.NET WebAPI2: การเพิ่มคำอธิบายฟังก์ชั่น API ใน Help Page

หลังจากที่ผมได้มีโอกาสพัฒนางานด้วย ASP.NET MVC Web API บน Visual Studio 2015 พบว่า เครื่องมือช่วยสร้าง Help Page โดยอัตโนมัติจากฟังก์ชั่นที่ได้เตรียมไว้ใน ApiController สำหรับให้ข้อมูลว่า Project นี้มี API ใดให้บริการบ้าง มีวิธีการเรียกใช้ และ มีรูปแบบของผลลัพธ์ เป็นอย่างไร แต่สิ่งที่หายไปคือ คำอธิบาย API (Description) นั่นเอง ดูภาพประกอบที่ 1

รูปที่ 1 – Web API Help Page ที่เครื่องมือเตรียมไว้ให้

เพื่อให้หน้า Help Page แสดงข้อมูลได้ครบถ้วน ผู้พัฒนาต้องตั้งค่า และ ดำเนินงานต่างๆ นี้

ขั้นที่ 1 กำหนด Property ของ Project

1. คลิกขวาที่ Project เลือก Properties
2. เลือกแถบ Build ที่ส่วน Output คลิกเลือก XML documentation file และระบุชื่อไฟล์ที่ต้องการ ซึ่งในบทความต่างๆ แนะนำให้จัดเก็บไฟล์ไว้ใน App_Data ดูภาพประกอบที่ 2

รูปที่ 2 กำหนด XML document

ขั้นที่ 2 เปิดการทำงาน DocumentationProvider

1. เปิดไฟล์ HelpPageConfig.cs
2. ลบเครื่องหมาย comment (//) ที่บรรทัด config.SetDocumentationProvider ดูภาพที่ 3 ประกอบ
3. ตรวจสอบและแก้ไขชื่อไฟล์ให้ตรงกับชื่อไฟล์ที่กำหนดไว้ใน รูปที่ 2
   ข้อควรระวัง: สัญลักษณ์ Path ที่ใช้ในรูปที่ 2 และ 3 ต่างด้านกัน เนื่องจากเป็น Path ของ Physical Drive และ URL Path ตามลำดับ

รูปที่ 3 เปิดการทำงาน DocumentationProvider

ขั้นที่ 3 เพิ่มคำอธิบายฟังก์ชั่น

1. วาง Cursor เหนือชื่อฟังก์ชั่น และ กดแป้น / 3 ครั้งต่อเนื่อง เพื่อวาง Summary Tag
2. เพิ่มคำอธิบายฟังก์ชั่น ระหว่าง ช่อง <summary>…</summary> และ คำอธิบายค่าตัวแปรระหว่างช่อง <param>…</param>
3. หลังจาก Build Project จะได้ข้อมูลในรูปแบบ XML ในไฟล์ที่ได้กำหนดไว้
4. เมื่อ Run Project และไปยังหน้า Help Page จะปรากฎรายละเอียดต่างๆ จากไฟล์ XML

รูปที่ 4 ใส่คำอธิบายใน Summary Tag

NONTAPON RATTANAPITTAYAPORN

More Posts