ทำความรู้จักกับเจ้า apiDoc กัน

Chayangkoon Dokhom
Sep 6, 2018 · 2 min read

คำโปรยในเว็บ apiDoc คือ Inline Documentation for RESTful web APIs

ซึ่งช่วงเวลาที่ผ่านมาเดือนสองเดือน ในทีมทำงานเกี่ยวกับ api ซะเยอะ ผมจึงได้รู้จักกับ lib ตัวนี้

หน้าตาตัวอย่างของเว็บก็ตาม link นี้เลย อ้างอิงจาก http://apidocjs.com/

ผมใช้ apiDoc กับ reactjs นะครับ ซึ่งจริงๆ ตามคู่มือมันก็รองรับหลายๆภาษา อะ เกริ่นซะเนินนาน มาเริ่มทำความรู้จักกับเจ้า apidoc กันดีกว่า


นำ apiDoc มาใช้กับ project

yarn add apidoc

แล้วสร้างไฟล์โครงสร้างตามนี้นะครับ หรือตามแต่ใจท่านจะต้องการ(หากเปลี่ยนโครงสร้างก็ จะต้องไปเปลี่ยน scripts ตาม)

โครงสร้างคร่าวๆ

หลังจากนั้นเพิ่มลองเพิ่ม code ต่างๆตามไฟล์ด้านล่างนี้

จากนั้นสร้างไฟล์ example.js และ example2.js

หลังจากนั้นเพิ่ม code ตามนี้

พอวาง code ทุกอย่างเป็นที่เรียบร้อย run คำสั่ง “yarn apidoc” ได้เลย

แล้วเราจะได้โฟลเดอร์ des มา หน้าตาประมาณนี้

ซึ่งหน้า apidoc จะอยู่ที่ไฟล์ index.html

หน้าตาก็จะประมาณนี้

ตามตัวอย่างก็จะได้หน้า doc มาใช้อย่างงดงาม(คล้ายๆ example)


นี้ก็เป็นวิธีการติดตั้ง และใช้ apiDoc เบื้องต้น จริงๆ อยากจะอธิบายวิธีการเขียนแต่ละหน้าให้ด้วย แต่กลัวจะทำให้บล็อคยาวจนเกินไป จึงขอทิ้งท้ายด้วยข้อดี และข้อเสียตามความเห็นส่วนตัว

เป็น lib ที่ค่อนข้างจะสะดวกสบายในการใช้เขียน doc ของ api สามารถทำ doc แยกเป็น version ได้ ฟังก์ชั่นต่างๆ รองรับกับการเขียนเป็น doc สำหรับ api แถมในไฟล์ สามารถแก้ได้โดยการเขียน html อย่าง <br> <code> เข้าใจง่าย

แต่ข้อเสียหลักๆ ที่เจอคือหน้าเว็บอ่านยาก ในมุมมองของผมนะ เข้าใจยากพอสมควร และการใช้ฟังก์ชั่น จะมีความเกี่ยวข้องกัน ซึ่งหากเราใช้ผิดลำดับหรือขาดไป จะไม่มี error แต่ก็จะได้ผลที่ต่างออกไปแทน(จริงๆ มันคงไม่ error แหละ แต่ผมคงอ่าน doc ไม่รู้เรื่องเอง)


ไว้ถ้ามีโอกาสได้ใช้ apiDoc อย่างเชี่ยวชาญ จะมาเขียนการทำงานของแต่ละฟังก์ชั่น

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade