[PHP] มาทำ Document ด้วย apiDoc กันเต๊อะ

จั่วหัวมาก็เมื๊องเมืองเลยเน๊าะ บ่งบอกได้เลยว่าเป็นคนที่ไหน ... วันนี้มาเร็วไปเร็วเหมือนเช่นทุกที ด้วยเหตุที่เมื่อสิ้นปีที่ผ่านเกิดเหตุการไม่คาดฝัน... ตัวข้าพเจ้าเองเลยโดนย้ายมาปฏิบัติภาระกิจอันแสนสำคัญ นั่นคือการทำ API ให้ Mobile .... เหยดดดดดดดดดดด

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

อันนี้เว็บหลัก http://apidocjs.com
ส่วนอันนี้เป็นการติดตั้ง http://apidocjs.com/#getting-started
มาดูตัวอย่างกันเลยดีกว่า สมมุตว่าผมมี Route อยู่ตัวหนึ่ง

#demoroute.php
class DemoRoute extends BaseRoute {

    /**
    * @api {get} /demo/example example title
    * @apiDescription Simple example description
    * @apiName DemoExample
    * @apiGroup Demo
    */
    public function example(){}
}

มาดูกันที่ตัวแรกครับ
@api {get} /demo/example example title
{get} ก็เป็นตัวบอกว่าเป็น Method อะไรเช่น get, post, put, delete ตามมาตรฐาน Restful ทั่วไป
 /demo/example เป็น url ที่เข้าถึงตัว API ตัวนี้
 example title เป็นหัวข้อที่จะแสดงในเมนู

@apiDescription แสดงรายละเอียด
@apiName ชื่อ API
@apiGroup จัดหมวดหมู่

รายละเอียดส่วนที่เหลือเข้าไปอ่านได้ที่ http://apidocjs.com/#params

ทีนี้มาถึงจุดที่จะต้อง Generate ตัว Document ขึ้นมาแล้วครับ ก็ทำการเปิดตัว Terminal ขึ้นมาแล้วเข้าไปที่ Directory ของโปรเจคเราแล้วพิมพ์เข้าไปว่า

apidoc -i . -o doc/

ตรง . จะเป็นการบ่งบอกว่ากำลังอ่านไฟล์ใน Dir นี้อยู่นะ ส่วน doc/ จะเป็นการสร้าง Document ที่เป็น Directory ชื่อว่า doc ขึ้นมา

พอเราเปิดเบราเซอร์ขึ้นมาแล้วเข้าไปที่โปรเจคเราเช่น http://demo.dev/doc/ ก็จะเจอกับ Document แล้วจ้า

เย้เย