หลังจากที่ developer ฝั่งหลังบ้านสู้ทนนั่งหลังขดหลังแข็ง implement แต่ละฟีเจอร์จนเสร็จเป็นที่เรียบร้อย จะมีอีกหนึ่งงานที่เหล่า backend ต้องทำนั่นคือการเขียน API Doc ซึ่งถือได้ว่าเป็นงานที่เร่งด่วนพอตัว

ประสบการณ์ได้เคยลองใช้ postman แต่ก็รู้สึกหงุดหงิดที่ให้ต้องเขียนเป็นภาษา markdown และวุ่นวายกับการพิมพ์ข้อความที่ยังไม่รองรับภาษาไทย และปัจจัยอื่นเล็ก ๆ น้อย ๆ

การค้นพบของ library ที่ชื่อว่า apidoc ทำให้ชีวิตได้พบเจอคำตอบ บอกได้เลยว่าตอบโจทย์

วิธีการสร้าง API Doc นั้นง่าย เพียงให้เราเพิ่ม comment ตรงไหนก็ได้ในโปรเจค แล้วก็ป้อนคำสั่งให้ระบบมัน generate เอกสารของ API Doc Spec ออกมาแสดงให้เราเป็นเว็บไซต์

Example ผลลัพธ์สุดท้ายที่ได้

Example ของ comment ที่เขียนไว้ในโค้ดเรา

วิธีการนำมาใช้กับ expressjs ของ nodejs

คำสั่งใช้สร้างเว็บ apidoc

apidoc -i src/ -o public/apidoc

หลังจากรันคำสั่งเสร็จ จะมี folder ชื่อ apidoc ใน pubilc ในโปรเจคเรา ซึ่งในนั้นมีไฟล์ต่างๆ เป็นรูปแบบ static website

วิธีเข้าถึงเว็บ

localhost:9090/apidoc

*ข้อควรระวัง

ความแตกต่างของ os เมื่อสั่ง generate apidoc ให้ตรวจเช็คดู path เพราะการเข้าถึงไฟล์ต่างกัน ตัวอย่างที่แชร์ใน post นี้รันบน macOS

*** apidoc ให้เราจัดเรียงกลุ่มของ API และแสดงวิธีการเข้าถึงแต่ละ API ออกมาเป็นแบบ side bar ช่วยให้เราที่เป็น backend และ frontend ดูง่าย และดีต่อใจ

ข้อมูลที่เกี่ยวข้อง

https://apidocjs.com/#getting-started